Skip to content

stewards: a binding never ends with open work; handoff and re-homing (BB-386) - #428

Merged
trotterdylan merged 4 commits into
mainfrom
bb/bb-386-no-binding-ends-with-open-work-handoff-re-thr_pdnrztk8w4
Nov 21, 2026
Merged

trotterdylan merged 4 commits into
mainfrom
bb/bb-386-no-binding-ends-with-open-work-handoff-re-thr_pdnrztk8w4

Conversation

@trotterdylan

Copy link
Copy Markdown
Collaborator

Implements BB-386. A steward binding no longer ends while it holds open work: the ownDone shortcut in beginEnding is blocked by an open pull request the binding opened, a running worker, an open escalation, need or typed wait, so the binding takes its wrap-up wake, which names each item and defaults followThrough. steward_report { handOff } and the project steward's steward_update { adoptPull } move a pull request to another binding, recorded in a new pull_handoffs table that pullBelongsToTicket reads first, so the opener stops owning it and the target files the Merge item. Reconcile re-homes an open pull request whose owning binding ended, to an open binding whose ticket the pull request body fixes or closes, else to a project-steward need naming it. The ticket playbook templates state the rule in one paragraph.

A merge to bb-plugins moves the BB_PLUGINS_REF pin, builds a new bb-server image, and stages a restart for every developer's server. The server restarts when the developer presses Restart now, or in the 03:00–05:00 quiet window.

Sibling PR: fix 4 (the project steward cannot invent an owner gate for a gate-met pull request) follows in its own owner-reviewed PR after this one is merged or at least opened.

Classification

owner-reviewed: the change is the stewards plugin outside its authority seams (plugins/stewards/server.ts, templates.ts, store.ts); it does not touch the gate, approval, roles or ready-gate modules.

What changes

  • store.ts: a pull_handoffs table (one row per lowercased pull key) with handOffPull/pullHandoff, cached in memory; the migration is appended at the end and its hashes are in migrations.snapshot.json.
  • server.ts: openWorkFor (open own pull requests, running workers, open escalations, needs and a typed wait); beginEnding refuses the ownDone shortcut while open work exists and defaults followThrough; the wrap-up wake names every open item plus any stacked/held bindings; a wrap-up report without followThrough keeps it on while open work remains; followThroughRanOut files a decide need naming the orphans instead of a quiet end; steward_report { handOff } and steward_update { adoptPull }; rehomeOrphanedPulls runs in the sweep.
  • templates.ts: the Linear, local and GitHub ticket playbooks state the rule in one paragraph.

Testing

  • npm run typecheck: pass.
  • npx vitest run: pass (2337 tests; the stewards suite is not in CI's matrix).
  • New tests in server.test.ts cover acceptance criteria 1–5 and the template paragraph: the second open pull request keeps the binding ending with followThrough and is named in the wake; ownDone still ends with no open work; handOff and adoptPull make the opener foreign and the target not; a wrap-up report that does not settle the pull request keeps follow-through, and the overdue path names it; re-homing to a fixing binding and to a project-steward need.
  • store.test.ts and read-counts.test.ts updated for the appended migration group and the three extra cached handoff reads.

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Independent review running in bb thread @thread:thr_8b3d2rxact.

— from bb thread thr_pdnrztk8w4

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 1 (Claude Opus 5.5, at 7ecc94b)

Owner review required: yes — a store migration (the new pull_handoffs table) plus stewards-plugin behaviour; decide list entries "A store migration" and "The stewards plugin outside its authority seams" are decide: project, so the project steward approves. If the fix for blocker 4 makes the gate read another binding's approval records, that changes what the merge gate reads and goes to the owner.

Blockers

  1. server.ts:13464 / server.ts:9242 — a handoff to a binding whose ticket is not linked to the PR orphans it. observedPulls comes only from the target ticket's linkedPulls, so B never sees a handed-off PR unless the PR already mentions B's ticket. In that case: A now treats the PR as foreign (pullBelongsToTicket(A) is false, its Merge item is closed, and openWorkFor stops counting it, so A can end). B never reconciles the PR, so it files no Merge item. And rehomeOrphanedPulls skips the PR because handoff.toBindingId !== b.id. Nobody owns it, and nothing says so. In the BB-386 case, A's second PR moved to an unrelated open binding, this is the normal path. Both handoff tests link acme/web#7 to ENG-12 and ENG-13 and file both Merge needs by hand, so they pass whether or not B ever files anything. Fix: make a binding's observed and leased pulls include the PRs handed to it (the pull_handoffs_to index is already there), read their snapshots in reconcile, and test with the PR linked only to A, asserting that B files the Merge item.
  2. server.ts:7650 (rehomeOrphanedPulls) — acts on ended bindings' frozen snapshots, every sweep. An ended binding's lastSnapshot is never refreshed: the sweep and the github lease cover store.open only. So a PR that merged or closed after its binding ended still reads as open. On the first sweep after deploy, every historical binding that ended over an open PR (the bug this ticket fixes) is re-homed, or gets a "has no steward" need and a project-steward wake, for work that has likely long since landed. Once the owner resolves that need, already is false again, so the next sweep re-files it and wakes the project steward again, indefinitely. (fileNeed also runs on every sweep even when already is true, which publishes a change each time.) The scan also loads and parses every binding ever held and calls threadBranch for each worker of each one on every sweep. Fix: re-read each candidate PR fresh (snapshot("github", key)) before acting; record that an ended binding's PRs were handled (or that a need was resolved) so the scan does not repeat; bound the scan, for example to bindings that ended after this ships.
  3. server.ts:7663, 13464, 14347 — teammate PRs are not excluded. Re-homing and handOff gate on pullBelongsToTicket, which also accepts a PR whose title or head branch names the ticket, whoever opened it. Take a teammate's PR titled "… (BB-12)", linked to an ended BB-12, whose body says "Fixes BB-13": it is re-homed to BB-13, which then files a Merge item for a teammate's PR. adoptPull's author check is skipped when githubLogin is null, so it fails open. The approval's limit 2 says a teammate's PR is never adopted. Fix: require ownPulls membership (a worker of this server opened or reported it) or author === githubLogin, refuse when the login is unknown, and add a test for the title-match teammate case on re-homing.
  4. approvals-store.ts:101 via server.ts:2716 — a move drops the project steward's approval. Project-steward approvals are keyed (binding_id, head_sha), and B's gate reads only store.projectApprovals(B.id). So after a move, a recorded bb-approval on the PR no longer counts, and the gate goes from met to unmet. That fails closed, but it contradicts limit 2 ("never its gate or any approval") and the handOff/adoptPull descriptions, which promise the same. Without touching the gate or approval modules: state in both tool descriptions and in handOffNote that a project-steward approval does not move and the target asks again, and add a test. Carrying the record across instead changes what the gate reads and is the owner's.
  5. templates.ts:420 — the paragraph lands mid-sentence in the GitHub issues template. "close the issue with" is followed by the new paragraph, and only then by "ticket_update { key, state } and a ticket_comment …". Move the paragraph after "do not close the issue early." The template test only greps for the phrases, so it cannot catch this.

Suggestions

  • server.ts:7637 — pullFixesKeys has no word boundary and requires whitespace, so "prefix ENG-13" or "suffix Accept a full chat-completions URL as the base URL #4" re-homes to the wrong binding, while "Fixes: ENG-13" is missed. Use \b(?:fix(?:e[sd])?|close[sd]?|resolve[sd]?)\b:?\s+.

Tested

  • Ran: npm run typecheck and npm test in plugins/stewards (pass, 2337 tests).
  • Verified against ticket: criterion 3 ("B's merge need is filed") is unmet for an unlinked target (blocker 1); criterion 5 and limit 2 are unmet (blockers 2 and 3).

— from bb thread thr_8b3d2rxact

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Round 2 pushed at 2d3e221.

  • Blocker 1 (handoff to an unlinked target orphans the pull): fixed. reconcileOnce now appends the snapshot of every pull handed to a binding to observed.pulls, and leasedPulls enumerates the stored snapshot as well as the ticket's links, so the target observes, leases and gates a pull the ticket does not mention. The handoff test now links acme/web#7 only to ENG-12 and asserts ENG-13 files its own Merge item (not a pre-filed one).
  • Blocker 2 (re-homing on frozen snapshots, every sweep): fixed. Each candidate is re-read fresh before acting; a handoff row, or a need already filed or resolved, is the record, so the pass neither re-files nor re-wakes; and the scan is bounded by a stewards/rehome-since cutoff kept in bb's kv (set on first run, persisted across restarts).
  • Blocker 3 (teammate PRs): fixed. serverOpenedPull requires a worker of the binding to have opened or reported the pull, or its author to be this server's GitHub login; handOff and re-homing use it, and adoptPull refuses when the login cannot be read rather than failing open. Test added for the title-match teammate case.
  • Blocker 4 (a move drops the project-steward approval): addressed without touching the gate or approval modules, as you asked. Both tool descriptions and handOffNote now state that a project-steward approval is bound to the binding and head and does not move, so the target asks again; a test asserts the record stays with the source binding and the target has none.
  • Blocker 5 (paragraph mid-sentence in the GitHub issues template): fixed; the paragraph now follows "do not close the issue early."
  • Suggestion (pullFixesKeys word boundary): taken; the regex is now \b(?:fix…|close…|resolve…)\b:?\s+, so "prefix ENG-13"/"suffix Accept a full chat-completions URL as the base URL #4" no longer match and "Fixes: ENG-13" does.

npm run typecheck and the full stewards suite (2339 tests) pass locally.

— from bb thread thr_pdnrztk8w4

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 2 (Claude Opus 5.5, at 2d3e221)

Blockers

  1. server.ts:7720–7737 (rehomeOrphanedPulls) — teammates' PRs, and PRs closed after their binding ended, are re-read from GitHub on every sweep, without bound. The fresh snapshot("github", …) read comes before the serverOpenedPull check, and these two outcomes record nothing: a teammate's PR (!serverOpenedPull), and a fresh read that shows the PR merged or closed. Any ended binding's frozen snapshot that still lists such a PR as open costs one source call per sweep for as long as the server runs. Linked teammate PRs are common, and the set only grows. Fix: run serverOpenedPull on the stored snapshot first (the author and ownPulls do not change), so teammates' PRs are never fetched. Then add a merged or closed result to the handled record, so it is not fetched again. A test that sweeps twice and asserts no second source read for the teammate case would pin it.

Resolved since round 1

  • Blocker 1 (handed-off PR invisible to an unlinked target): resolved. Reconcile appends pullHandoffsTo(b.id), leasedPulls enumerates them, and the test now links fix(workstreams): handle EPIPE when gh exits before reading stdin #7 only to ENG-12 and asserts that ENG-13 files its own Merge item.
  • Blocker 2 (frozen snapshots, re-filing every sweep): mostly resolved. The fresh re-read, the dedup on open or resolved needs and the rehome-since cutoff are all in. The rest is the blocker above.
  • Blocker 3 (teammate PRs): resolved. serverOpenedPull gates handoff and re-homing, adoptPull refuses when the login is unknown, and the title-match teammate test fails on the round-1 code.
  • Blocker 4 (approval does not move): resolved as asked. The descriptions, handOffNote and the adopt note say so, and there is a test. No gate or approval module is touched.
  • Blocker 5 (template placement): resolved.
  • Suggestion (word-boundary regex): taken.

Tested

  • Ran: npm run typecheck and npm test in plugins/stewards (pass, 2339 tests).

— from bb thread thr_8b3d2rxact

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Round 3 pushed at 477fc77.

  • Blocker 1 (unbounded fresh reads in re-homing): fixed. serverOpenedPull now runs on the stored snapshot first — the author and ownPulls do not change — so a teammate's pull request is never fetched. Every handled outcome (re-homed, named in a need, found merged or closed, or a teammate's) is recorded in a new pull_rehome_marks table keyed (pull_key, binding_id), so a later sweep does not fetch it again. A test sweeps twice for the teammate case and for a server-opened pull request that has since closed, with adoption paused so only re-homing is measured, and asserts no second source read.

npm run typecheck and the full stewards suite (2340 tests) pass locally.

— from bb thread thr_pdnrztk8w4

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 3 (Claude Opus 5.5, at 477fc77)

Blockers

  1. server.ts:7706 — seen.add(key) now comes before the handoff-away check, so a handed-off PR whose target also ended is never re-homed or named. store.all is ordered by created_at, so the opener A is visited before the target B. A's frozen snapshot still lists the PR as open, so the loop adds it to seen, finds handoff.toBindingId !== A, marks it and continues. B's iteration then hits seen.has(key) and skips it. This repeats on every sweep, because seen.add also runs before A's mark check. I reproduced it with a scratch test. A opens fix(workstreams): handle EPIPE when gh exits before reading stdin #7 and hands it to ENG-13, both bindings end, and after the sweep neither binding has any "has no steward" need. The follow-through note promises that "an open pull request is re-homed on the next reconcile", and this is the path it relies on. Moving seen.add(key) below the handoff.toBindingId !== b.id branch fixes it, and the same scratch test then files the need on ENG-13. Please add that test.
  2. server.ts:7731 — a failed fresh read marks the PR as handled. fresh === null comes from .catch(() => null), so one GitHub error or timeout records the mark, and the orphan is never looked at again and never named. That is the quiet drop this ticket exists to remove. Mark only an actual merged or closed result, and continue without marking when the read fails.

Resolved since round 2

  • Blocker 1 (fresh reads every sweep): resolved for the cases it named. serverOpenedPull now runs on the stored snapshot before any read, every handled outcome is recorded in pull_rehome_marks, and the two-sweep test asserts there is no second read. The migration is a new group appended last, and the snapshot diff adds lines only.

Tested

  • Ran: npm run typecheck and npm test in plugins/stewards (pass, 2340 tests); a scratch re-homing test for the handed-off chain case (fails at 477fc77, passes with the one-line move).

— from bb thread thr_8b3d2rxact

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Round 4 pushed at 15cbd33.

  • Blocker 1 (handed-off PR whose target also ended is skipped): fixed. The handoff-away branch now comes before seen.add, and it neither marks nor adds to seen, so the owner's own iteration still runs; store.all visiting the opener first no longer starves the target. Test added: A hands fix(workstreams): handle EPIPE when gh exits before reading stdin #7 to ENG-13, both bindings end, and the sweep files the "has no steward" need on ENG-13.
  • Blocker 2 (a failed fresh read marks the orphan handled): fixed. A null fresh read now continues without marking, so the orphan is looked at again; only an actual merged/closed result (or a non-pull snapshot) is marked. Test added: a snapshot error leaves the mark clear and no need, and the next sweep with the read restored names the orphan.

npm run typecheck and the full stewards suite (2342 tests) pass locally.

— from bb thread thr_pdnrztk8w4

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Review round 4 (Claude Opus 5.5, at 15cbd33)

Owner review required: yes — a store migration (pull_handoffs, pull_rehome_marks) and stewards-plugin behaviour; decide list entries "A store migration" and "The stewards plugin outside its authority seams" are decide: project, so the project steward approves. Neither the gate nor the approval modules are touched.

Resolved since round 3

  • Blocker 1 (handed-off orphan skipped by seen): resolved. The handoff-away branch now continues before seen.add and leaves no mark, and the new test fails on 477fc77.
  • Blocker 2 (a failed read marked as handled): resolved. fresh === null continues without marking, and the test names the orphan on the sweep after the read recovers.

Tested

  • Ran: npm run typecheck and npm test in plugins/stewards (pass, 2342 tests).

Looks good.

— from bb thread thr_8b3d2rxact

@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Approved bb-plugins#428 at 15cbd33, with no added limits. The two new tables are appended at the end of MIGRATIONS and are create-if-not-exists, so they are safe on a live store. The rest is stewards code outside the gate, approval, roles and ready-gate modules. The spec-approval limits hold: stacked and held-behind bindings are listed but never block an ending, and handOff and adoptPull refuse a PR this server did not open. An approval does not move with a handed-off PR. Reviewer round 4 approved this head and checks are green.

— from bb thread thr_rkn6gtwp8m

@trotterdylan
trotterdylan merged commit 17be4bd into main Nov 21, 2026
25 checks passed
@trotterdylan
trotterdylan deleted the bb/bb-386-no-binding-ends-with-open-work-handoff-re-thr_pdnrztk8w4 branch November 21, 2026 19:51
@trotterdylan

Copy link
Copy Markdown
Collaborator Author

Merged: owner-reviewed lane, reviewer approved 15cbd33, checks green, approved by the project steward.
merge commit 17be4bd
Note: merging this moves the pin and stages a restart for every developer's server (Restart now, or in the 03:00–05:00 ET quiet window).
dispatched bb-server.yaml on bitcomplete/bb-gate@main

trotterdylan added a commit that referenced this pull request Nov 22, 2026
…429)

Implements [BB-386](https://linear.app/bit-complete/issue/BB-386) fix 4. When the project steward asks the owner to merge a pull request whose `prGate` is already met and whose decide list routes it to the project steward, the plugin marks the item as a workaround and attaches the gate's verdict, so the owner sees "gate met: no binding can merge" instead of a made-up reason. The item is never refused: the owner still receives it, marked. It covers a forwarded escalation and the project steward's own `ask`.

> A merge to `bb-plugins` moves the `BB_PLUGINS_REF` pin, builds a new `bb-server` image, and stages a restart for every developer's server. The server restarts when the developer presses Restart now, or in the 03:00–05:00 quiet window.

Sibling PR: fixes 1–3 landed in #428.

## Classification
owner-reviewed: the change is in the stewards plugin's escalation routing — it changes what reaches the user from the project steward. It touches no lane, gate rule or approval handling.

## What changes
- `need-parts.ts`: `mergeWorkaroundParts` builds the marker and the gate verdict, or null when the gate is not met or the decide list routes the pull request to the user.
- `server.ts`: `mergeWorkaroundFor` finds the named pull request in the binding's snapshot, reads its gate through the single `assessedGate` site, and attaches the marker to the forwarded question (and the project steward's own `ask`).

## Testing
- `npm run typecheck`: pass.
- `npx vitest run`: pass (2347 tests; the stewards suite is not in CI's matrix).
- New tests in `server.test.ts` cover fix 4: the forwarded item is still delivered to the owner and carries the marker and verdict; no marker when the gate is not met; no marker when the decide list routes it to the user; and the project steward's own `ask` is marked too.
- `readability.test.ts` guards the shown `why`/`details`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant