fix(gate): preserve explicit --branch, require a hint cross-repo, fix empty-branch guard

Three follow-up fixes to bd gate discover's cross-repo matching:

- branchFilterForRepo collapsed "user passed --branch" and "auto-detected
  local branch" into one string, so an explicit --branch was dropped for
  every foreign-repo query exactly like the un-requested auto-detected one -
  `bd gate discover --branch main` silently did nothing cross-repo. Capture
  userSpecifiedBranch before the auto-detect fallback and keep the filter for
  a foreign repo when the user specified it.

- With commit/branch heuristics neutralized for a foreign repo, a hintless
  gate could still reach bestScore >= 30 on time proximity + in-progress/
  queued status alone and pin the wrong run in another repository
  permanently. matchGateToRun now refuses to match a foreign gate with no
  workflow name hint at all; matchGatesToRuns skips the query entirely for
  that case (and, when a hint IS present for a foreign repo, now passes it
  through as `gh run list --workflow <hint>` to recover the visibility
  --limit would otherwise cost an unfiltered cross-repo query).

- Heuristic 2 (branch match) didn't guard against an empty currentBranch
  (git branch detection failure) the way Heuristic 1 already guards
  currentCommit - mirrored the same non-empty check so a run with an empty
  HeadBranch can't accidentally "match" it.

Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
This commit is contained in:
matt wilkie 2026-08-01 13:50:58 -07:00
commit 4718138a5f
2 changed files with 226 additions and 51 deletions

View file

@ -103,7 +103,14 @@ func runGateDiscover(cmd *cobra.Command, args []string) error {
fmt.Printf("%s Found %d gate(s) awaiting run ID discovery\n\n", ui.RenderAccent("🔍"), len(gates))
if branchFilter == "" {
// userSpecifiedBranch must be captured BEFORE the auto-detect fallback
// below overwrites branchFilter with the local branch - otherwise
// branchFilterForRepo can never tell "the user explicitly asked to
// filter by this branch" apart from "this is just the local branch we
// defaulted to", and an explicit `--branch` is dropped for every
// cross-repo gate exactly like the un-requested auto-detected one is.
userSpecifiedBranch := branchFilter != ""
if !userSpecifiedBranch {
branchFilter = getGitBranchForGateDiscovery()
}
@ -112,8 +119,8 @@ func runGateDiscover(cmd *cobra.Command, args []string) error {
// queried FROM that repository, never against a same-named workflow run
// from the current repo. matchGatesToRuns groups gates by their
// validated repo and issues one query per distinct repo.
matches := matchGatesToRuns(gates, maxAge, func(repo string) ([]GHWorkflowRun, error) {
return queryGitHubRunsInRepo(branchFilterForRepo(branchFilter, repo), limit, repo)
matches := matchGatesToRuns(gates, maxAge, func(repo, workflowHint string) ([]GHWorkflowRun, error) {
return queryGitHubRunsInRepo(branchFilterForRepo(branchFilter, repo, userSpecifiedBranch), limit, repo, workflowHint)
})
// Step 3/4: report matches (and, outside dry-run, persist them)
@ -222,13 +229,18 @@ func gateDiscoveryQueryFailures(matches []gateDiscoveryMatch) map[string]error {
}
// branchFilterForRepo returns the branch filter to use when querying a gate's
// repo. It only applies the local branch filter to the current repo
// (repo == ""); a cross-repo gate's target branch has no relationship to the
// branch checked out locally, so `gh run list --repo <other> --branch
// <local-branch>` would filter out every run in that repo and the gate would
// never be discoverable (this was the cross-repo-discovery-is-inert bug).
func branchFilterForRepo(localBranchFilter, repo string) string {
if repo != "" {
// repo. It always applies the branch filter to the current repo (repo ==
// ""). For a foreign repo it drops an auto-detected local branch - a
// cross-repo gate's target branch has no relationship to the branch checked
// out locally, so `gh run list --repo <other> --branch <local-branch>` would
// filter out every run in that repo and the gate would never be discoverable
// (this was the cross-repo-discovery-is-inert bug) - but keeps a branch the
// user explicitly passed via `--branch`: an explicit filter is a deliberate
// instruction about the TARGET repo's branch, not a guess about the local
// checkout, and dropping it silently for cross-repo gates would make
// `bd gate discover --branch main` appear to work while doing nothing.
func branchFilterForRepo(localBranchFilter, repo string, userSpecified bool) string {
if repo != "" && !userSpecified {
return ""
}
return localBranchFilter
@ -237,13 +249,21 @@ func branchFilterForRepo(localBranchFilter, repo string) string {
// matchGatesToRuns scopes run discovery per gate's own repo selector (SF1).
// Gates are grouped by their validated metadata.repo (via githubRepoFromIssue;
// "" means the current repository), and queryRuns is called at most once per
// distinct repo among the given gates. A gate is only ever matched against
// runs queried from ITS repo - never against another repo's runs of a
// same-named workflow, which would otherwise persist the wrong await_id
// permanently (the persisted ID pins the gate).
func matchGatesToRuns(gates []*types.Issue, maxAge time.Duration, queryRuns func(repo string) ([]GHWorkflowRun, error)) []gateDiscoveryMatch {
runsByRepo := make(map[string][]GHWorkflowRun)
queryErrByRepo := make(map[string]error)
// distinct (repo, workflow hint) pair among the given gates. A gate is only
// ever matched against runs queried from ITS repo - never against another
// repo's runs of a same-named workflow, which would otherwise persist the
// wrong await_id permanently (the persisted ID pins the gate).
//
// queryRuns receives a workflowHint - the gate's AwaitID workflow name hint,
// non-empty only for a foreign (cross-repo) query - so it can narrow the
// `gh run list` call with --workflow. Without that narrowing, a busy foreign
// repo's unfiltered recent-run list (capped by --limit) might never surface
// the specific workflow a gate is waiting on. The current repo's query is
// never narrowed this way (workflowHint is always "" for it), matching
// pre-existing `bd gate discover` behavior for local gates.
func matchGatesToRuns(gates []*types.Issue, maxAge time.Duration, queryRuns func(repo, workflowHint string) ([]GHWorkflowRun, error)) []gateDiscoveryMatch {
runsByKey := make(map[string][]GHWorkflowRun)
queryErrByKey := make(map[string]error)
results := make([]gateDiscoveryMatch, 0, len(gates))
for _, gate := range gates {
@ -253,19 +273,40 @@ func matchGatesToRuns(gates []*types.Issue, maxAge time.Duration, queryRuns func
continue
}
runs, cached := runsByRepo[repo]
foreign := repo != ""
hint := getWorkflowNameHint(gate)
// Cross-repo discovery requires a workflow hint. With local-commit/
// local-branch heuristics neutralized for a foreign repo (see
// matchGateToRun), a hintless gate could only ever score on time
// proximity alone and risk pinning the wrong run in another
// repository permanently. Skip the query entirely rather than spend
// a GitHub API call on a gate that can never match.
if foreign && hint == "" {
results = append(results, gateDiscoveryMatch{gate: gate})
continue
}
queryHint := ""
key := repo
if foreign {
queryHint = hint
key = repo + "\x1f" + hint
}
runs, cached := runsByKey[key]
if !cached {
if qErr, queried := queryErrByRepo[repo]; queried {
if qErr, queried := queryErrByKey[key]; queried {
results = append(results, gateDiscoveryMatch{gate: gate, err: &gateQueryError{repo: repo, err: qErr}})
continue
}
queried, err := queryRuns(repo)
queried, err := queryRuns(repo, queryHint)
if err != nil {
queryErrByRepo[repo] = err
queryErrByKey[key] = err
results = append(results, gateDiscoveryMatch{gate: gate, err: &gateQueryError{repo: repo, err: err}})
continue
}
runsByRepo[repo] = queried
runsByKey[key] = queried
runs = queried
}
@ -273,7 +314,7 @@ func matchGatesToRuns(gates []*types.Issue, maxAge time.Duration, queryRuns func
// against the current repo's runs; a foreign repo (repo != "") never
// shares a commit SHA or branch name with the local checkout, so
// those heuristics are neutralized for it (see matchGateToRun).
results = append(results, gateDiscoveryMatch{gate: gate, run: matchGateToRun(gate, runs, maxAge, repo != "")})
results = append(results, gateDiscoveryMatch{gate: gate, run: matchGateToRun(gate, runs, maxAge, foreign)})
}
return results
@ -389,19 +430,22 @@ func getGitCommitForGateDiscovery() string {
}
// queryGitHubRunsInRepo queries recent workflow runs from GitHub using gh
// CLI, scoped to repo ("" means the current repository). This is the query
// path for `bd gate discover`'s branch/heuristic matching (SF1) - distinct
// from queryGitHubRunsForWorkflowInRepo in gate.go, which filters by a
// specific --workflow name for the direct await_id discovery used by
// `bd gate check`.
func queryGitHubRunsInRepo(branch string, limit int, repo string) ([]GHWorkflowRun, error) {
// CLI, scoped to repo ("" means the current repository) and optionally
// narrowed to a single workflow (workflow == "" queries all workflows). This
// is the query path for `bd gate discover`'s branch/heuristic matching (SF1)
// - distinct from queryGitHubRunsForWorkflowInRepo in gate.go, which filters
// by a specific --workflow name for the direct await_id discovery used by
// `bd gate check`. matchGatesToRuns only ever passes a non-empty workflow for
// a foreign repo, to recover the visibility --limit would otherwise cost an
// unfiltered cross-repo query (see matchGatesToRuns).
func queryGitHubRunsInRepo(branch string, limit int, repo string, workflow string) ([]GHWorkflowRun, error) {
if _, err := exec.LookPath("gh"); err != nil {
return nil, fmt.Errorf("gh CLI not found: install from https://cli.github.com")
}
return queryGitHubRunsInRepoWithRunner(branch, limit, repo, runGHCommand)
return queryGitHubRunsInRepoWithRunner(branch, limit, repo, workflow, runGHCommand)
}
func queryGitHubRunsInRepoWithRunner(branch string, limit int, repo string, runGH ghCommandRunner) ([]GHWorkflowRun, error) {
func queryGitHubRunsInRepoWithRunner(branch string, limit int, repo string, workflow string, runGH ghCommandRunner) ([]GHWorkflowRun, error) {
args := []string{
"run", "list",
"--json", "databaseId,displayTitle,headBranch,headSha,name,status,conclusion,createdAt,updatedAt,workflowName,url",
@ -414,6 +458,9 @@ func queryGitHubRunsInRepoWithRunner(branch string, limit int, repo string, runG
if repo != "" {
args = append(args, "--repo", repo)
}
if workflow != "" {
args = append(args, "--workflow", workflow)
}
output, stderr, err := runGH(args...)
if err != nil {
@ -440,13 +487,24 @@ func queryGitHubRunsInRepoWithRunner(branch string, limit int, repo string, runG
// describe the current checkout, not the foreign repo - so the commit/branch
// heuristics are skipped entirely rather than comparing against them anyway.
func matchGateToRun(gate *types.Issue, runs []GHWorkflowRun, maxAge time.Duration, foreignRepo bool) *GHWorkflowRun {
workflowHint := getWorkflowNameHint(gate)
// Cross-repo discovery requires a workflow hint. With the commit/branch
// heuristics below neutralized for a foreign repo, a hintless gate could
// otherwise reach bestScore >= 30 on time proximity (+ in-progress/queued
// status) alone and pin the wrong run in another repository permanently -
// matchGatesToRuns already skips the query for this case, but guard here
// too so any other caller gets the same safety.
if foreignRepo && workflowHint == "" {
return nil
}
now := time.Now()
var currentCommit, currentBranch string
if !foreignRepo {
currentCommit = getGitCommitForGateDiscovery()
currentBranch = getGitBranchForGateDiscovery()
}
workflowHint := getWorkflowNameHint(gate)
var bestMatch *GHWorkflowRun
var bestScore int
@ -477,10 +535,12 @@ func matchGateToRun(gate *types.Issue, runs []GHWorkflowRun, maxAge time.Duratio
score += 100
}
// Heuristic 2: Branch match. Skipped for a foreign repo
// (currentBranch is "" there; a run with an empty HeadBranch, if
// GitHub ever returns one, must not accidentally "match" it).
if !foreignRepo && run.HeadBranch == currentBranch {
// Heuristic 2: Branch match. Skipped for a foreign repo (see
// Heuristic 1) and mirrors its currentCommit != "" guard: if local
// branch detection failed, currentBranch is "" and a run with an
// empty HeadBranch (if GitHub ever returns one) must not
// accidentally "match" it.
if !foreignRepo && currentBranch != "" && run.HeadBranch == currentBranch {
score += 50
}

View file

@ -34,12 +34,18 @@ func TestMatchGatesToRuns_ScopesPerGateRepo(t *testing.T) {
}
queryCalls := map[string]int{}
queryRuns := func(repo string) ([]GHWorkflowRun, error) {
queryRuns := func(repo, workflowHint string) ([]GHWorkflowRun, error) {
queryCalls[repo]++
switch repo {
case "":
if workflowHint != "" {
t.Errorf("current-repo query got workflowHint %q, want empty (only foreign queries are narrowed)", workflowHint)
}
return []GHWorkflowRun{{DatabaseID: 111, Name: "release", WorkflowName: "release.yml", Status: "in_progress", CreatedAt: time.Now()}}, nil
case "other-owner/other-repo":
if workflowHint != "release.yml" {
t.Errorf("cross-repo query got workflowHint %q, want %q", workflowHint, "release.yml")
}
return []GHWorkflowRun{{DatabaseID: 222, Name: "release", WorkflowName: "release.yml", Status: "in_progress", CreatedAt: time.Now()}}, nil
default:
t.Fatalf("unexpected repo queried: %q", repo)
@ -92,7 +98,7 @@ func TestMatchGatesToRuns_RejectsInvalidRepoMetadata(t *testing.T) {
}
queried := false
queryRuns := func(repo string) ([]GHWorkflowRun, error) {
queryRuns := func(repo, workflowHint string) ([]GHWorkflowRun, error) {
queried = true
return nil, nil
}
@ -122,7 +128,7 @@ func TestMatchGatesToRuns_CachesQueryErrorPerRepo(t *testing.T) {
queryCalls := 0
wantErr := errors.New("gh run list failed: rate limited")
queryRuns := func(repo string) ([]GHWorkflowRun, error) {
queryRuns := func(repo, workflowHint string) ([]GHWorkflowRun, error) {
queryCalls++
return nil, wantErr
}
@ -138,6 +144,40 @@ func TestMatchGatesToRuns_CachesQueryErrorPerRepo(t *testing.T) {
}
}
// TestMatchGatesToRuns_ForeignGateWithoutHintNeverQueried covers the query
// half of the "cross-repo discovery requires a hint" fix: a foreign gate
// with no workflow name hint can never match (matchGateToRun always returns
// nil for it), so matchGatesToRuns must skip the GitHub query entirely for
// it rather than spend an API call on a gate that can't be discovered.
func TestMatchGatesToRuns_ForeignGateWithoutHintNeverQueried(t *testing.T) {
gate := &types.Issue{
ID: "bd-cross-no-hint",
AwaitType: "gh:run",
CreatedAt: time.Now(),
Metadata: json.RawMessage(`{"repo":"other-owner/other-repo"}`),
}
queried := false
queryRuns := func(repo, workflowHint string) ([]GHWorkflowRun, error) {
queried = true
return nil, nil
}
results := matchGatesToRuns([]*types.Issue{gate}, 30*time.Minute, queryRuns)
if len(results) != 1 {
t.Fatalf("got %d results, want 1", len(results))
}
if results[0].err != nil {
t.Errorf("gate %s: unexpected error: %v", results[0].gate.ID, results[0].err)
}
if results[0].run != nil {
t.Errorf("expected no matched run for a hintless foreign gate, got %+v", results[0].run)
}
if queried {
t.Error("expected no GitHub query for a foreign gate with no workflow hint")
}
}
// TestGateDiscoveryQueryFailures_DetectsFailedQueries covers the SF-fix
// exit-code regression: before per-repo scoping, any GitHub query error was
// fatal (HandleError, exit 1). After scoping queries per gate repo, a failed
@ -152,7 +192,7 @@ func TestGateDiscoveryQueryFailures_DetectsFailedQueries(t *testing.T) {
wantErrA := errors.New("gh CLI not found")
wantErrB := errors.New("rate limited")
queryRuns := func(repo string) ([]GHWorkflowRun, error) {
queryRuns := func(repo, workflowHint string) ([]GHWorkflowRun, error) {
if repo == "other-owner/other-repo" {
return nil, wantErrB
}
@ -181,7 +221,7 @@ func TestGateDiscoveryQueryFailures_IgnoresMetadataErrors(t *testing.T) {
gate := &types.Issue{ID: "bd-bad-repo", AwaitType: "gh:run", AwaitID: "release.yml", CreatedAt: time.Now(),
Metadata: json.RawMessage(`{"repo":null}`)}
queryRuns := func(repo string) ([]GHWorkflowRun, error) {
queryRuns := func(repo, workflowHint string) ([]GHWorkflowRun, error) {
t.Fatal("expected no GitHub query for a gate with malformed repo metadata")
return nil, nil
}
@ -192,37 +232,86 @@ func TestGateDiscoveryQueryFailures_IgnoresMetadataErrors(t *testing.T) {
}
}
// TestBranchFilterForRepo covers the cross-repo-discovery-is-inert fix: the
// local branch filter must never be forwarded to a foreign repo's query -
// a cross-repo gate's target branch has no relationship to the branch
// checked out locally, so filtering that repo's runs by it would match
// nothing, forever.
// TestBranchFilterForRepo covers the cross-repo-discovery-is-inert fix: an
// AUTO-DETECTED local branch filter must never be forwarded to a foreign
// repo's query - a cross-repo gate's target branch has no relationship to
// the branch checked out locally, so filtering that repo's runs by it would
// match nothing, forever. But an EXPLICIT `--branch` must survive for a
// foreign repo too: it is a deliberate instruction about the target repo's
// branch, not a guess about the local checkout, and dropping it silently
// would make `bd gate discover --branch main` appear to work cross-repo
// while actually doing nothing.
func TestBranchFilterForRepo(t *testing.T) {
tests := []struct {
name string
localBranchFilter string
repo string
userSpecified bool
want string
}{
{name: "current repo keeps branch filter", localBranchFilter: "feature/foo", repo: "", want: "feature/foo"},
{name: "foreign repo drops branch filter", localBranchFilter: "feature/foo", repo: "other-owner/other-repo", want: ""},
{name: "foreign repo drops empty branch filter too", localBranchFilter: "", repo: "other-owner/other-repo", want: ""},
{name: "current repo keeps auto-detected branch filter", localBranchFilter: "feature/foo", repo: "", userSpecified: false, want: "feature/foo"},
{name: "current repo keeps explicit branch filter", localBranchFilter: "main", repo: "", userSpecified: true, want: "main"},
{name: "foreign repo drops auto-detected branch filter", localBranchFilter: "feature/foo", repo: "other-owner/other-repo", userSpecified: false, want: ""},
{name: "foreign repo drops empty auto-detected branch filter too", localBranchFilter: "", repo: "other-owner/other-repo", userSpecified: false, want: ""},
{name: "foreign repo keeps explicit branch filter", localBranchFilter: "main", repo: "other-owner/other-repo", userSpecified: true, want: "main"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := branchFilterForRepo(tt.localBranchFilter, tt.repo); got != tt.want {
t.Errorf("branchFilterForRepo(%q, %q) = %q, want %q", tt.localBranchFilter, tt.repo, got, tt.want)
if got := branchFilterForRepo(tt.localBranchFilter, tt.repo, tt.userSpecified); got != tt.want {
t.Errorf("branchFilterForRepo(%q, %q, %v) = %q, want %q", tt.localBranchFilter, tt.repo, tt.userSpecified, got, tt.want)
}
})
}
}
// TestMatchGateToRun_ForeignRepoWithoutHintNeverMatches covers the follow-up
// fix to the cross-repo-discovery-is-inert bug: neutralizing the commit/
// branch heuristics for a foreign repo (see the test below) is not enough by
// itself - a hintless foreign gate can still reach bestScore >= 30 on time
// proximity (+30) plus an in-progress/queued run (+5) alone, and pinning that
// run's ID onto the gate would be just as wrong as the commit/branch
// coincidence this fix set out to prevent (the persisted await_id pins the
// gate permanently). A foreign gate therefore must never match without a
// workflow name hint, full stop - regardless of what score the remaining
// heuristics would otherwise produce.
func TestMatchGateToRun_ForeignRepoWithoutHintNeverMatches(t *testing.T) {
gate := &types.Issue{
ID: "bd-cross-no-hint",
AwaitType: "gh:run",
// AwaitID intentionally empty: no workflow name hint.
CreatedAt: time.Now(),
}
runs := []GHWorkflowRun{
{
DatabaseID: 777,
Status: "in_progress", // +5
CreatedAt: time.Now(), // within 5 minutes of gate.CreatedAt: +30
},
}
// Sanity check: the same run does score >= 30 for a non-foreign gate on
// time proximity + status alone (commit/branch won't coincidentally
// match empty HeadSha/HeadBranch against this repo's real values), so
// the foreign case below isn't vacuously nil for an unrelated reason.
if got := matchGateToRun(gate, runs, 30*time.Minute, false); got == nil {
t.Fatal("non-foreign gate: expected time-proximity+status alone to select the run")
}
if got := matchGateToRun(gate, runs, 30*time.Minute, true); got != nil {
t.Errorf("foreign gate without a workflow hint: expected no match, got run %d", got.DatabaseID)
}
}
// TestMatchGateToRun_NeutralizesLocalHeuristicsForForeignRepo covers the
// scoring half of the cross-repo-discovery-is-inert fix: run.HeadSha and
// run.HeadBranch describe a run in the FOREIGN repo, so comparing them
// against the local checkout's commit/branch is meaningless (and could
// spuriously "match" by coincidence). A run that would only match a
// non-foreign gate by commit/branch heuristics must not match a foreign one.
// (This gate has no workflow hint either, so the result is now also covered
// by TestMatchGateToRun_ForeignRepoWithoutHintNeverMatches's stricter,
// hint-independent guard - both are kept because they document distinct
// failure modes the fix addresses.)
func TestMatchGateToRun_NeutralizesLocalHeuristicsForForeignRepo(t *testing.T) {
localCommit := getGitCommitForGateDiscovery()
localBranch := getGitBranchForGateDiscovery()
@ -262,6 +351,7 @@ func TestQueryGitHubRunsInRepoWithRunner(t *testing.T) {
"main",
10,
"srobroek/agentic-packages",
"",
fakeGHRunner(t,
`[{"databaseId":555,"name":"release","status":"completed","conclusion":"success","workflowName":"release.yml"}]`,
"run", "list", "--json", "databaseId,displayTitle,headBranch,headSha,name,status,conclusion,createdAt,updatedAt,workflowName,url", "--limit", "10", "--branch", "main", "--repo", "srobroek/agentic-packages",
@ -280,6 +370,7 @@ func TestQueryGitHubRunsInRepoWithRunner_OmitsRepoFlagForCurrentRepo(t *testing.
"",
10,
"",
"",
fakeGHRunner(t,
`[]`,
"run", "list", "--json", "databaseId,displayTitle,headBranch,headSha,name,status,conclusion,createdAt,updatedAt,workflowName,url", "--limit", "10",
@ -289,3 +380,27 @@ func TestQueryGitHubRunsInRepoWithRunner_OmitsRepoFlagForCurrentRepo(t *testing.
t.Fatalf("queryGitHubRunsInRepoWithRunner returned error: %v", err)
}
}
// TestQueryGitHubRunsInRepoWithRunner_AddsWorkflowFlagForForeignRepo covers
// the narrowing half of the cross-repo-discovery-is-inert fix: a foreign
// repo's query is narrowed with --workflow when matchGatesToRuns has a hint,
// recovering the visibility --limit would otherwise cost an unfiltered
// cross-repo query.
func TestQueryGitHubRunsInRepoWithRunner_AddsWorkflowFlagForForeignRepo(t *testing.T) {
runs, err := queryGitHubRunsInRepoWithRunner(
"",
10,
"srobroek/agentic-packages",
"release.yml",
fakeGHRunner(t,
`[]`,
"run", "list", "--json", "databaseId,displayTitle,headBranch,headSha,name,status,conclusion,createdAt,updatedAt,workflowName,url", "--limit", "10", "--repo", "srobroek/agentic-packages", "--workflow", "release.yml",
),
)
if err != nil {
t.Fatalf("queryGitHubRunsInRepoWithRunner returned error: %v", err)
}
if len(runs) != 0 {
t.Fatalf("runs = %#v, want none", runs)
}
}