From 371363aed8389b1d83deee421e7a864365b95e16 Mon Sep 17 00:00:00 2001 From: Ben Matson Date: Tue, 17 Nov 2026 07:11:34 -0700 Subject: [PATCH 1/7] test: The warning comment and the views The tests come first and fail until the implementation. A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged. Unit: merge-must-land-on-the-default-branch/4 --- src/agent_build_kit/pipeline/events.py | 16 +++ tests/cli/test_status_landing.py | 106 ++++++++++++++- tests/pipeline/test_base_merged_comment.py | 149 +++++++++++++++++++++ 3 files changed, 269 insertions(+), 2 deletions(-) create mode 100644 tests/pipeline/test_base_merged_comment.py diff --git a/src/agent_build_kit/pipeline/events.py b/src/agent_build_kit/pipeline/events.py index 89ae78458..f14d1b0cb 100644 --- a/src/agent_build_kit/pipeline/events.py +++ b/src/agent_build_kit/pipeline/events.py @@ -1305,6 +1305,22 @@ def retarget(unit: StoredUnit, base: str) -> bool: ) +def warn_base_merged( + store: UnitStore, + *, + base_on_host: Callable[[StoredUnit], str | None], + forge_of: Callable[[StoredUnit], tuple[Forge, RepoId]], + posts_root: Path, + log: Log = print, +) -> list[str]: + """Each round: post once, on the pull request of an in-review unit whose base branch has + merged and whose host base (`base_on_host`) is not yet the base its graph gives it, the + warning that it is being moved and is not to be merged until it shows the default branch. + The comment carries a marker line and its ids are recorded in the own-posts record under + `posts_root`, so a later round does not post it again. Returns the ids it posted for.""" + raise NotImplementedError + + def _unit_on_branch(store: UnitStore, repo: str, branch: str, not_id: str) -> StoredUnit | None: """The unit, other than `not_id`, whose branch is `branch` in `repo`.""" return next( diff --git a/tests/cli/test_status_landing.py b/tests/cli/test_status_landing.py index 178db8b0d..4ea27c68c 100644 --- a/tests/cli/test_status_landing.py +++ b/tests/cli/test_status_landing.py @@ -5,16 +5,21 @@ from __future__ import annotations +import argparse from pathlib import Path import pytest +from agent_build_kit.cli.explain_cmd import cmd_explain from agent_build_kit.forges.base import Check, CheckStatus +from agent_build_kit.installation import Installation from agent_build_kit.pipeline.pr_poller import HOLD_LABEL -from agent_build_kit.pipeline.units import IN_REVIEW +from agent_build_kit.pipeline.unit_store import Cause, UnitStore +from agent_build_kit.pipeline.units import HELD, IN_REVIEW, PLANNED from agent_build_kit.pipeline.verdict import ReviewTier from agent_build_kit.pipeline.verdict_record import VERDICTS -from tests.conftest import run_status +from tests.conftest import make_installation, run_status +from tests.factories import new_unit from tests.landing_support import PR, UNIT, Landing, landing from tests.verdict_fakes import write_verdicts @@ -99,3 +104,100 @@ def test_a_decline_ended_by_a_rework_is_no_longer_shown( assert lines assert not any("held by label" in line or "not landed" in line for line in lines) + + +PARENT = "feature/1" +DEPENDENT = "feature/2" +OFF_PR = 5 +OFF_BRANCH = f"spec/{PARENT}" + + +@pytest.fixture +def held_installation(tmp_path: Path) -> Installation: + return make_installation( + tmp_path, planning={"state_dir": ".", "worktree_root": str(tmp_path.parent / "trees")} + ) + + +def hold(inst: Installation, cause: Cause, note: str) -> None: + """`feature/1` held with `cause`, and `feature/2` parked on it.""" + store = UnitStore(inst.state_dir / "units.json") + store.upsert([new_unit(PARENT), new_unit(DEPENDENT, depends_on=(PARENT,))]) + store.set_state(PARENT, HELD, pr=OFF_PR, branch=OFF_BRANCH, note=note, cause=cause) + store.set_state(DEPENDENT, PLANNED, note="parked", cause=Cause.GATED) + store.set_needs(DEPENDENT, (PARENT,)) + + +def test_status_shows_a_unit_landed_off_the_default_branch_and_what_a_person_can_do( + held_installation: Installation, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + hold(held_installation, Cause.LANDED_OFF_DEFAULT, f"#{OFF_PR} was merged into {OFF_BRANCH}") + + lines = run_status(held_installation, monkeypatch, capsys) + + shown_lines = [line for line in lines if f"{PARENT} " in line and "landed off" in line] + assert len(shown_lines) == 1, "\n".join(lines) + shown = shown_lines[0] + assert "landed off the default branch" in shown + assert f"#{OFF_PR}" in shown + assert OFF_BRANCH in shown + assert "carry" in shown, "it says what a person can do" + + +def test_status_says_a_dependent_waits_on_a_unit_landed_off_the_default_branch( + held_installation: Installation, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + hold(held_installation, Cause.LANDED_OFF_DEFAULT, f"#{OFF_PR} was merged into {OFF_BRANCH}") + + lines = run_status(held_installation, monkeypatch, capsys) + + waiting = [line for line in lines if f"{DEPENDENT} " in line] + assert waiting + assert any("landed off the default branch" in line for line in waiting), "\n".join(lines) + + +def test_status_shows_a_unit_whose_base_was_not_moved_and_what_a_person_can_do( + held_installation: Installation, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], +) -> None: + hold(held_installation, Cause.BASE_NOT_MOVED, f"#{OFF_PR} could not be moved onto main") + + lines = run_status(held_installation, monkeypatch, capsys) + + shown_lines = [line for line in lines if f"{PARENT} " in line and "base not moved" in line] + assert len(shown_lines) == 1, "\n".join(lines) + shown = shown_lines[0] + assert f"#{OFF_PR}" in shown + assert "main" in shown + assert "retarget" in shown, "it says what a person can do" + + +@pytest.mark.parametrize( + ("cause", "words"), + [ + (Cause.LANDED_OFF_DEFAULT, ("landed off the default branch", OFF_BRANCH, "carry")), + (Cause.BASE_NOT_MOVED, ("base not moved", "main", "retarget")), + ], + ids=["landed-off-default", "base-not-moved"], +) +def test_explain_says_why_a_unit_is_held_for_these_causes( + held_installation: Installation, + capsys: pytest.CaptureFixture[str], + cause: Cause, + words: tuple[str, ...], +) -> None: + hold(held_installation, cause, f"#{OFF_PR} on {OFF_BRANCH}, wanted main") + capsys.readouterr() + + code = cmd_explain(argparse.Namespace(unit=PARENT, at=None), held_installation) + + out = capsys.readouterr().out + assert code == 0 + assert f"#{OFF_PR}" in out + for word in words: + assert word in out, out diff --git a/tests/pipeline/test_base_merged_comment.py b/tests/pipeline/test_base_merged_comment.py new file mode 100644 index 000000000..94d30abcb --- /dev/null +++ b/tests/pipeline/test_base_merged_comment.py @@ -0,0 +1,149 @@ +"""A child whose base branch has merged and whose retarget is pending gets one warning comment +on its pull request, recorded as the pipeline's own so the poller does not read it as a +reviewer's (spec: merge-landing). + +The forge is the shared stand-in, which keeps what was posted; the rounds are driven by calling +the step directly.""" + +from __future__ import annotations + +from pathlib import Path + +from agent_build_kit import forges +from agent_build_kit.forges import Forge, RepoId +from agent_build_kit.pipeline import events +from agent_build_kit.pipeline.pr_replies import MARKER, own_posts +from agent_build_kit.pipeline.unit_store import StoredUnit, UnitStore +from agent_build_kit.pipeline.units import IN_REVIEW +from tests.forges.stand_in import StandInForge +from tests.pipeline.test_retarget_retry import ( + CHILD, + PARENT, + PULL, + STALE_BASE, + WANTED_BASE, + child_behind_a_merged_parent, +) + + +class RememberingForge(StandInForge): + """A host that can say whether a comment carrying a marker is already on a pull request.""" + + def comment_exists( + self, repo: RepoId, pr: int, marker: str, body: str, *, reply_to: str | None = None + ) -> str | None: + return "comment-1" if any(marker in each for each in self.comments) else None + + +class Round: + """One store, one forge and the host's idea of each pull request's base.""" + + def __init__(self, tmp_path: Path) -> None: + self.store: UnitStore = child_behind_a_merged_parent(tmp_path) + self.forge = RememberingForge() + self.root = tmp_path / "posts" + self.root.mkdir() + self.bases: dict[str, str] = {CHILD: STALE_BASE} + + def base_on_host(self, unit: StoredUnit) -> str | None: + return self.bases.get(unit.id) + + def forge_of(self, unit: StoredUnit) -> tuple[Forge, RepoId]: + return self.forge, self.forge.repo_id() + + def run(self) -> list[str]: + return events.warn_base_merged( + self.store, + base_on_host=self.base_on_host, + forge_of=self.forge_of, + posts_root=self.root, + log=lambda _line: None, + ) + + def own(self) -> set[str]: + return own_posts(self.root, forges.key(self.forge.repo_id()), PULL) + + +def test_a_child_whose_retarget_is_pending_gets_one_comment_with_the_marker_line( + tmp_path: Path, +) -> None: + warn = Round(tmp_path) + + warn.run() + + [comment] = warn.forge.comments + assert MARKER in comment + assert WANTED_BASE in comment + assert "Do not merge" in comment + assert warn.forge.calls == [("comment", PULL)] + + +def test_the_comment_is_recorded_in_the_own_posts_record(tmp_path: Path) -> None: + warn = Round(tmp_path) + + warn.run() + + assert warn.own() == {"comment-1"} + + +def test_no_second_comment_follows_while_the_retarget_stays_pending(tmp_path: Path) -> None: + warn = Round(tmp_path) + + rounds = [warn.run() for _ in range(3)] + + assert len(warn.forge.comments) == 1 + assert rounds == [[CHILD], [], []] + + +def test_a_failed_retarget_that_holds_the_unit_does_not_bring_a_second_comment( + tmp_path: Path, +) -> None: + warn = Round(tmp_path) + warn.run() + warn.store.set_base_move_failures(CHILD, 2) + + warn.run() + + assert len(warn.forge.comments) == 1 + + +def test_a_child_already_on_its_base_gets_no_comment(tmp_path: Path) -> None: + warn = Round(tmp_path) + warn.bases[CHILD] = WANTED_BASE + + warned = warn.run() + + assert warned == [] + assert warn.forge.comments == [] + + +def test_a_child_whose_base_branch_has_not_merged_gets_no_comment(tmp_path: Path) -> None: + warn = Round(tmp_path) + warn.store.set_state(PARENT, IN_REVIEW, pr=1, branch=STALE_BASE) + + warned = warn.run() + + assert warned == [] + assert warn.forge.comments == [] + + +def test_a_child_whose_host_base_is_unknown_gets_no_comment(tmp_path: Path) -> None: + warn = Round(tmp_path) + warn.bases.clear() + + warn.run() + + assert warn.forge.comments == [] + + +def test_a_comment_the_host_refuses_is_not_recorded_and_is_tried_again(tmp_path: Path) -> None: + warn = Round(tmp_path) + warn.forge.comment_error = True + + warn.run() + + assert warn.own() == set() + warn.forge.comment_error = False + warn.run() + assert len(warn.forge.comments) == 1 + assert warn.own() == {"comment-1"} From bac13bbb9579f0ae3f3ff26a5a56752d557def2c Mon Sep 17 00:00:00 2001 From: Ben Matson Date: Tue, 17 Nov 2026 07:16:58 -0700 Subject: [PATCH 2/7] feat: The warning comment and the views With this in, the tests of the previous commit pass. A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged. Unit: merge-must-land-on-the-default-branch/4 --- CHANGELOG.md | 6 +++- src/agent_build_kit/cli/explain_cmd.py | 5 ++- src/agent_build_kit/cli/pipeline.py | 22 ++++++++++++- src/agent_build_kit/pipeline/events.py | 36 +++++++++++++++++++++- src/agent_build_kit/pipeline/unit_store.py | 17 ++++++++++ 5 files changed, 82 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 175047197..3575ab7cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,7 +21,11 @@ branch, as a carry or a person's merge puts it there. A review unit whose pull request is not on the base its stack gives it is now retargeted each round, the host's base is read back to confirm, and after three failed rounds the unit is held `base_not_moved` with the - pull request and the expected base named. + pull request and the expected base named. While that retarget is pending, one comment on the + pull request says its base has merged and that it is not to be merged until it shows the + default branch. `abk status` and `abk explain` show a unit held `landed_off_default` or + `base_not_moved` with its pull request, the branches and what a person can do, and a + dependent says it waits on a unit that landed off the default branch. - The rerun of a failed test now collects a test of the `integration` kind that a repository's default settings deselect. Before, the rerun carried no marker expression, so such a test was diff --git a/src/agent_build_kit/cli/explain_cmd.py b/src/agent_build_kit/cli/explain_cmd.py index 9bfc37a31..7f93f9ce4 100644 --- a/src/agent_build_kit/cli/explain_cmd.py +++ b/src/agent_build_kit/cli/explain_cmd.py @@ -18,7 +18,7 @@ from agent_build_kit.pipeline.external_file import external_reason, held_units from agent_build_kit.pipeline.regression_agent import waited_fixes from agent_build_kit.pipeline.resolution_lane import lane_record, resolving_phrase -from agent_build_kit.pipeline.unit_store import Cause +from agent_build_kit.pipeline.unit_store import Cause, landing_hold_text from agent_build_kit.pipeline.units import PLANNED, RUNNING, history_stamp @@ -168,6 +168,9 @@ def cmd_explain(args: argparse.Namespace, inst: Installation) -> int: ) if record is None: return 0 + if unit is not None and (landing := landing_hold_text(unit)): + print(f"{args.unit} is {landing}") + return 0 if record is None: print(f"no record covers {args.unit} at {at.isoformat()}") return 0 diff --git a/src/agent_build_kit/cli/pipeline.py b/src/agent_build_kit/cli/pipeline.py index d5e2b856e..65fa4bf98 100644 --- a/src/agent_build_kit/cli/pipeline.py +++ b/src/agent_build_kit/cli/pipeline.py @@ -161,10 +161,12 @@ build_retarget, conflict_phrase, late_check_running, + pr_base_on_host, pr_based_on, recheck_landings, remove_merged_branches, retry_host_retargets, + warn_base_merged, ) from agent_build_kit.pipeline.external_file import Hold as ExternalHold from agent_build_kit.pipeline.external_file import ( @@ -351,6 +353,7 @@ awaits_release, feedback_source_of, guidance_excerpt, + landing_hold_text, waiting_for, ) from agent_build_kit.pipeline.unit_test_slots import slot_status_lines, waiting_since @@ -1365,6 +1368,8 @@ def cmd_status(args: argparse.Namespace, inst: Installation) -> int: log(f" held by the checks: {unit.id} ({where}) — {unit.note}") if unit.state == HELD and unit.cause is Cause.DIRTY_WORKTREE: log(f" parked: {unit.id} ({where}) — {unit.note}") + if landing := landing_hold_text(unit): + log(f" held: {unit.id} ({where}) {landing}") if unit.state == RUNNING and unit.cause is Cause.LOGIN: log( f" paused for the login: {unit.id} ({where}) until it is renewed; " @@ -1402,7 +1407,14 @@ def cmd_status(args: argparse.Namespace, inst: Installation) -> int: if waits: merging = merge_parents(unit, waits, units, config.active().repos) wait = dependency_wait(waits, merging=merging) - log(f" {unit.id} ({where}) {wait}") + off = [ + "a parent landed off the default branch" + for parent in units + if parent.id in {each.id for each in waits} + and parent.state == HELD + and parent.cause is Cause.LANDED_OFF_DEFAULT + ] + log(f" {unit.id} ({where}) {wait}{''.join(f' — {each}' for each in off)}") if is_superseded(unit): log(f" superseded: {unit.id} ({where}) by {', '.join(unit.superseded_by)}") if unit.close_pending: @@ -7195,6 +7207,14 @@ def poll_all(inst: Installation, *, store: UnitStore, lane: Lane | None = None) resume=resume, log=log, ) + # The warning goes up before the retarget is tried, so a person sees it while the base is stale. + warn_base_merged( + store, + base_on_host=pr_base_on_host, + forge_of=lambda unit: inst.forge_of(unit.repo), + posts_root=inst.state_dir, + log=log, + ) retry_host_retargets(store, claim=claim, resume=resume, log=log) labels = StateLabels(inst.forge_of, log=log) diff --git a/src/agent_build_kit/pipeline/events.py b/src/agent_build_kit/pipeline/events.py index f14d1b0cb..9b5697bf2 100644 --- a/src/agent_build_kit/pipeline/events.py +++ b/src/agent_build_kit/pipeline/events.py @@ -1318,7 +1318,41 @@ def warn_base_merged( warning that it is being moved and is not to be merged until it shows the default branch. The comment carries a marker line and its ids are recorded in the own-posts record under `posts_root`, so a later round does not post it again. Returns the ids it posted for.""" - raise NotImplementedError + graph = store.all() + posted_for: list[str] = [] + for unit in graph: + if unit.state != IN_REVIEW or not unit.pr: + continue + on_host = base_on_host(unit) + wanted = base_of(unit, graph) + if on_host is None or on_host == wanted: + continue + if not any( + other.state in (MERGED, SATISFIED) + and other.repo == unit.repo + and other.branch == on_host + for other in graph + ): + continue + body = ( + f"The base branch `{on_host}` of this pull request has merged. It is being moved " + f"onto `{wanted}`. Do not merge it until it shows `{wanted}` as its base.\n{MARKER}" + ) + try: + forge, repo_id = forge_of(unit) + found = forge.comment_exists(repo_id, unit.pr, MARKER, body) + ids = [found] if found else forge.post_comment(repo_id, unit.pr, body=body) + except TRANSIENT as error: + log(f"{unit.id}: warning on #{unit.pr} not posted — {error}") + continue + if not ids: + log(f"{unit.id}: warning on #{unit.pr} not posted; tried again next round") + continue + record_posts(posts_root, forges.key(repo_id), unit.pr, ids) + if not found: + log(f"{unit.id}: warned on #{unit.pr} that its base {on_host} has merged") + posted_for.append(unit.id) + return posted_for def _unit_on_branch(store: UnitStore, repo: str, branch: str, not_id: str) -> StoredUnit | None: diff --git a/src/agent_build_kit/pipeline/unit_store.py b/src/agent_build_kit/pipeline/unit_store.py index a468fa1cb..cb66bad93 100644 --- a/src/agent_build_kit/pipeline/unit_store.py +++ b/src/agent_build_kit/pipeline/unit_store.py @@ -1953,6 +1953,23 @@ def waiting_for(unit: StoredUnit) -> str: return _WAITING_FOR.get(unit.cause, "") if unit.cause else "" +def landing_hold_text(unit: StoredUnit) -> str: + """What a unit held `landed_off_default` or `base_not_moved` says, with its pull request, + its note (the branches) and what a person can do; "" for any other unit.""" + pull = f"#{unit.pr}" if unit.pr else "its pull request" + if unit.state == HELD and unit.cause is Cause.LANDED_OFF_DEFAULT: + return ( + f"landed off the default branch: {pull} — {unit.note}; carry its work onto " + "the default branch, then release the hold" + ) + if unit.state == HELD and unit.cause is Cause.BASE_NOT_MOVED: + return ( + f"base not moved: {pull} — {unit.note}; retarget the pull request onto its " + "base by hand, then release the hold" + ) + return "" + + # How long a parked unit waits, by consecutive parking. PARK_BACKOFF = ( timedelta(minutes=1), From a77d5608ece5f1795b93571bc004927804ef6828 Mon Sep 17 00:00:00 2001 From: Ben Matson Date: Tue, 17 Nov 2026 07:21:06 -0700 Subject: [PATCH 3/7] test: Documents The tests come first and fail until the implementation. A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged. Unit: merge-must-land-on-the-default-branch/4 --- tests/docs/test_merge_landing_docs.py | 30 +++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 tests/docs/test_merge_landing_docs.py diff --git a/tests/docs/test_merge_landing_docs.py b/tests/docs/test_merge_landing_docs.py new file mode 100644 index 000000000..2b77e1451 --- /dev/null +++ b/tests/docs/test_merge_landing_docs.py @@ -0,0 +1,30 @@ +"""The architecture guide and the `abk-pipeline` skill say that a merge is recorded only when it is +on the default branch, and what `landed_off_default` and `base_not_moved` mean +(spec: merge-must-land-on-the-default-branch).""" + +from __future__ import annotations + +import pytest + +from tests.doc_text import ROOT +from tests.prompt_text import flat + +ARCHITECTURE = flat((ROOT / "docs" / "architecture.md").read_text()) +SKILL = flat( + (ROOT / "src" / "agent_build_kit" / "skills" / "abk-pipeline" / "SKILL.md").read_text() +) + + +def test_the_architecture_says_a_merge_is_recorded_only_when_on_the_default_branch() -> None: + assert "recorded only when" in ARCHITECTURE + assert "default branch" in ARCHITECTURE + + +@pytest.mark.parametrize("cause", ["landed_off_default", "base_not_moved"]) +def test_the_architecture_explains_the_cause_beyond_the_list_of_causes(cause: str) -> None: + assert ARCHITECTURE.count(f"`{cause}`") >= 2 + + +@pytest.mark.parametrize("cause", ["landed_off_default", "base_not_moved"]) +def test_the_skill_mentions_the_cause(cause: str) -> None: + assert f"`{cause}`" in SKILL From 9154efa49bd09d5ae8f4d3d2e4c7cbbe673c70c5 Mon Sep 17 00:00:00 2001 From: Ben Matson Date: Tue, 17 Nov 2026 07:22:49 -0700 Subject: [PATCH 4/7] feat: Documents With this in, the tests of the previous commit pass. A unit's pull request can be merged into a branch that is not the default one: its parent's branch, left in place after the parent merged. Unit: merge-must-land-on-the-default-branch/4 --- docs/architecture.md | 5 +++++ src/agent_build_kit/skills/abk-pipeline/SKILL.md | 7 +++++++ 2 files changed, 12 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index b5f1f75bd..630269b4a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -948,6 +948,11 @@ A standing cause names a situation that lasts until a state change passes anothe `restack_deferred`, `restack_handed_back`, `dirty_worktree`, `attached`, `host_unavailable`, `network_unavailable`, `service_unavailable`, `environment`, `split_held`, `manual_step`, `too_big_for_tier`, `landed_off_default` (a pull request merged into a branch that is not the default branch) and `base_not_moved` (a pull request whose retarget failed three rounds in a row). +A merge is recorded only when it is on the default branch. A pull request merged into the branch +of a unit that had already merged leaves its unit held `landed_off_default`, and its dependents +keep waiting, until its commit reaches the default branch. A pull request that is not on the base +its stack gives it is retargeted each round and the host's base read back; after three failed +rounds the unit is held `base_not_moved`. An event cause names a transition that has happened and is over: `requeued`, `released`, `adopted`, `merged`, `auto_landed`, `closed`, `retired`, `superseded` and `failed`. Recording an event cause ends a standing one explicitly. A state change the store makes on its own account (a replan's demotion and diff --git a/src/agent_build_kit/skills/abk-pipeline/SKILL.md b/src/agent_build_kit/skills/abk-pipeline/SKILL.md index 0a6e09780..10823309e 100644 --- a/src/agent_build_kit/skills/abk-pipeline/SKILL.md +++ b/src/agent_build_kit/skills/abk-pipeline/SKILL.md @@ -347,6 +347,13 @@ default branch`. It holds no claim on the unit while it waits or runs, so `abk settle --accept` works then, and a result that comes back after an accept changes nothing. +A merge is recorded only when it is on the default branch. A pull request merged into the branch +of a unit that already merged leaves its unit held `landed_off_default` (its dependents keep +waiting) until its commit reaches the default branch, as a carry or a person's merge puts it there. +A review unit whose pull request cannot be retargeted onto the base its stack gives it is held +`base_not_moved` after three failed rounds; `abk status` and `abk explain` name the pull request, +the branches and what a person can do. + ### Paused for a rejected login When an account's Claude login is rejected (the CLI says `Failed to authenticate`, HTTP 401, `OAuth From 5369b8587febf8b7692726e39f7e7fafa9c09939 Mon Sep 17 00:00:00 2001 From: Ben Matson Date: Tue, 17 Nov 2026 08:17:02 -0700 Subject: [PATCH 5/7] fix: The warning comment, the status and explain views, and documents (checks, round 1) Unit: merge-must-land-on-the-default-branch/4 --- docs/architecture.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 630269b4a..aa8494b28 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -948,11 +948,6 @@ A standing cause names a situation that lasts until a state change passes anothe `restack_deferred`, `restack_handed_back`, `dirty_worktree`, `attached`, `host_unavailable`, `network_unavailable`, `service_unavailable`, `environment`, `split_held`, `manual_step`, `too_big_for_tier`, `landed_off_default` (a pull request merged into a branch that is not the default branch) and `base_not_moved` (a pull request whose retarget failed three rounds in a row). -A merge is recorded only when it is on the default branch. A pull request merged into the branch -of a unit that had already merged leaves its unit held `landed_off_default`, and its dependents -keep waiting, until its commit reaches the default branch. A pull request that is not on the base -its stack gives it is retargeted each round and the host's base read back; after three failed -rounds the unit is held `base_not_moved`. An event cause names a transition that has happened and is over: `requeued`, `released`, `adopted`, `merged`, `auto_landed`, `closed`, `retired`, `superseded` and `failed`. Recording an event cause ends a standing one explicitly. A state change the store makes on its own account (a replan's demotion and @@ -975,6 +970,12 @@ unit put back for any other cause waits for the next pass, and the tick log says still on as `held_base`, and who holds it as `held_by`. A record with no cause is one from before causes or one an event ended, and one with a cause this release does not know reads the same way: the pass never readmits it, and `abk status` lists it. +A merge is recorded only when it is on the default branch. A pull request merged into the branch +of a unit that had already merged leaves its unit held `landed_off_default`, and its dependents +keep waiting, until its commit reaches the default branch. A pull request that is not on the base +its stack gives it is retargeted each round and the host's base read back; after three failed +rounds the unit is held `base_not_moved`. + **The code host outage.** A git push the code host refuses (an authentication refusal, an HTTP 401, 403 or 5xx, a connection it closed), or cannot reach while the control group is up, parks its unit with the cause `host_unavailable`, and a fetch it refuses or cannot reach is noted without parking its unit. The call that From e5676e88798ad34162d125cda1388b4ca5d431a8 Mon Sep 17 00:00:00 2001 From: Ben Matson Date: Tue, 17 Nov 2026 09:50:40 -0700 Subject: [PATCH 6/7] fix: The warning comment, the status and explain views, and documents (review round 1) Unit: merge-must-land-on-the-default-branch/4 --- CHANGELOG.md | 2 +- src/agent_build_kit/pipeline/events.py | 19 +++++++++-------- tests/forges/stand_in.py | 9 ++++++++ tests/pipeline/test_base_merged_comment.py | 24 ++++++++++++---------- tests/pipeline/test_close_kept.py | 14 ++----------- 5 files changed, 35 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3575ab7cb..0d5782d08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,7 +23,7 @@ back to confirm, and after three failed rounds the unit is held `base_not_moved` with the pull request and the expected base named. While that retarget is pending, one comment on the pull request says its base has merged and that it is not to be merged until it shows the - default branch. `abk status` and `abk explain` show a unit held `landed_off_default` or + base its stack gives it. `abk status` and `abk explain` show a unit held `landed_off_default` or `base_not_moved` with its pull request, the branches and what a person can do, and a dependent says it waits on a unit that landed off the default branch. diff --git a/src/agent_build_kit/pipeline/events.py b/src/agent_build_kit/pipeline/events.py index 9b5697bf2..dc3f49428 100644 --- a/src/agent_build_kit/pipeline/events.py +++ b/src/agent_build_kit/pipeline/events.py @@ -1315,7 +1315,8 @@ def warn_base_merged( ) -> list[str]: """Each round: post once, on the pull request of an in-review unit whose base branch has merged and whose host base (`base_on_host`) is not yet the base its graph gives it, the - warning that it is being moved and is not to be merged until it shows the default branch. + warning that it is being moved and is not to be merged until it shows the base its stack + gives it. The comment carries a marker line and its ids are recorded in the own-posts record under `posts_root`, so a later round does not post it again. Returns the ids it posted for.""" graph = store.all() @@ -1323,16 +1324,16 @@ def warn_base_merged( for unit in graph: if unit.state != IN_REVIEW or not unit.pr: continue - on_host = base_on_host(unit) wanted = base_of(unit, graph) - if on_host is None or on_host == wanted: - continue - if not any( - other.state in (MERGED, SATISFIED) - and other.repo == unit.repo - and other.branch == on_host + merged_branches = { + other.branch for other in graph - ): + if other.state in (MERGED, SATISFIED) and other.repo == unit.repo + } + if not merged_branches - {wanted}: + continue # No merged branch could be its stale base: the host need not be asked. + on_host = base_on_host(unit) + if on_host is None or on_host == wanted or on_host not in merged_branches: continue body = ( f"The base branch `{on_host}` of this pull request has merged. It is being moved " diff --git a/tests/forges/stand_in.py b/tests/forges/stand_in.py index 763b24bc1..36852b2f5 100644 --- a/tests/forges/stand_in.py +++ b/tests/forges/stand_in.py @@ -342,6 +342,15 @@ def labels_on(self, *args, **kwargs) -> list[str]: raise NotImplementedError +class FindingForge(StandInForge): + """A host that finds a comment it holds by its marker and exact body, as the real reads do.""" + + def comment_exists( + self, repo: RepoId, pr: int, marker: str, body: str, *, reply_to: str | None = None + ) -> str | None: + return "comment-1" if any(marker in c and body == c for c in self.comments) else None + + def lookup(forge: StandInForge): """A `for_repo` the `wiring.build_*` factories accept: every repo name resolves to this one stand-in.""" diff --git a/tests/pipeline/test_base_merged_comment.py b/tests/pipeline/test_base_merged_comment.py index 94d30abcb..3c9f26410 100644 --- a/tests/pipeline/test_base_merged_comment.py +++ b/tests/pipeline/test_base_merged_comment.py @@ -15,7 +15,7 @@ from agent_build_kit.pipeline.pr_replies import MARKER, own_posts from agent_build_kit.pipeline.unit_store import StoredUnit, UnitStore from agent_build_kit.pipeline.units import IN_REVIEW -from tests.forges.stand_in import StandInForge +from tests.forges.stand_in import FindingForge from tests.pipeline.test_retarget_retry import ( CHILD, PARENT, @@ -26,26 +26,19 @@ ) -class RememberingForge(StandInForge): - """A host that can say whether a comment carrying a marker is already on a pull request.""" - - def comment_exists( - self, repo: RepoId, pr: int, marker: str, body: str, *, reply_to: str | None = None - ) -> str | None: - return "comment-1" if any(marker in each for each in self.comments) else None - - class Round: """One store, one forge and the host's idea of each pull request's base.""" def __init__(self, tmp_path: Path) -> None: self.store: UnitStore = child_behind_a_merged_parent(tmp_path) - self.forge = RememberingForge() + self.forge = FindingForge() self.root = tmp_path / "posts" self.root.mkdir() self.bases: dict[str, str] = {CHILD: STALE_BASE} + self.asked: list[str] = [] def base_on_host(self, unit: StoredUnit) -> str | None: + self.asked.append(unit.id) return self.bases.get(unit.id) def forge_of(self, unit: StoredUnit) -> tuple[Forge, RepoId]: @@ -127,6 +120,15 @@ def test_a_child_whose_base_branch_has_not_merged_gets_no_comment(tmp_path: Path assert warn.forge.comments == [] +def test_the_host_is_not_asked_about_a_unit_with_no_merged_base(tmp_path: Path) -> None: + warn = Round(tmp_path) + warn.store.set_state(PARENT, IN_REVIEW, pr=1, branch=STALE_BASE) + + warn.run() + + assert warn.asked == [] + + def test_a_child_whose_host_base_is_unknown_gets_no_comment(tmp_path: Path) -> None: warn = Round(tmp_path) warn.bases.clear() diff --git a/tests/pipeline/test_close_kept.py b/tests/pipeline/test_close_kept.py index 79b15540b..2375b01a8 100644 --- a/tests/pipeline/test_close_kept.py +++ b/tests/pipeline/test_close_kept.py @@ -5,27 +5,17 @@ import pytest from agent_build_kit.cli import pipeline as cli -from agent_build_kit.forges import RepoId from agent_build_kit.forges.base import COMMENT_MARKER from agent_build_kit.pipeline.unit_store import ClosePending, UnitStore from agent_build_kit.pipeline.units import IN_REVIEW, PLANNED, SATISFIED, Unit, UnitState from agent_build_kit.pipeline.wiring import build_close_pr from tests.factories import stored_unit, unit -from tests.forges.stand_in import StandInForge, lookup +from tests.forges.stand_in import FindingForge, lookup REASON = "Task group(s) 1 are implemented elsewhere." ID = "add-marker/1" -class Remembering(StandInForge): - """A host that finds a comment it holds by its marker and body, as the real reads do.""" - - def comment_exists( - self, repo: RepoId, pr: int, marker: str, body: str, *, reply_to: str | None = None - ) -> str | None: - return "comment-1" if any(marker in c and body == c for c in self.comments) else None - - def pending_store(tmp_path: Path, *, pending: ClosePending | None) -> UnitStore: store = UnitStore(tmp_path / "units.json") store.upsert([stored_unit()]) @@ -36,7 +26,7 @@ def pending_store(tmp_path: Path, *, pending: ClosePending | None) -> UnitStore: def test_the_reason_is_posted_once_when_the_close_fails_and_is_repeated() -> None: - host = Remembering(close_error="502 Bad Gateway") + host = FindingForge(close_error="502 Bad Gateway") close = build_close_pr(for_repo=lookup(host)) with pytest.raises(RuntimeError): close(unit(), 4, REASON) From 79392e7b7c4e9ff0b177e24fc9e686b8fba5d2f4 Mon Sep 17 00:00:00 2001 From: Ben Matson Date: Tue, 17 Nov 2026 11:03:10 -0700 Subject: [PATCH 7/7] fix: The warning comment, the status and explain views, and documents (review round 2) Unit: merge-must-land-on-the-default-branch/4 --- src/agent_build_kit/pipeline/events.py | 17 +++++++++++++---- tests/pipeline/test_base_merged_comment.py | 14 ++++++++++++++ 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/src/agent_build_kit/pipeline/events.py b/src/agent_build_kit/pipeline/events.py index dc3f49428..e5cc3c78a 100644 --- a/src/agent_build_kit/pipeline/events.py +++ b/src/agent_build_kit/pipeline/events.py @@ -121,6 +121,7 @@ depth_of, is_superseded, local_ref, + reachable, through_satisfied, trunk_of, ) @@ -1320,18 +1321,26 @@ def warn_base_merged( The comment carries a marker line and its ids are recorded in the own-posts record under `posts_root`, so a later round does not post it again. Returns the ids it posted for.""" graph = store.all() + by_id = {other.id: other for other in graph} posted_for: list[str] = [] for unit in graph: if unit.state != IN_REVIEW or not unit.pr: continue wanted = base_of(unit, graph) + ancestors = reachable( + unit.depends_on, + lambda uid: by_id[uid].depends_on if uid in by_id else (), + ) merged_branches = { - other.branch - for other in graph - if other.state in (MERGED, SATISFIED) and other.repo == unit.repo + by_id[uid].branch + for uid in ancestors + if uid in by_id + and by_id[uid].repo == unit.repo + and by_id[uid].state in (MERGED, SATISFIED) + and by_id[uid].branch } if not merged_branches - {wanted}: - continue # No merged branch could be its stale base: the host need not be asked. + continue # None of its own ancestors could be its stale base: do not ask the host. on_host = base_on_host(unit) if on_host is None or on_host == wanted or on_host not in merged_branches: continue diff --git a/tests/pipeline/test_base_merged_comment.py b/tests/pipeline/test_base_merged_comment.py index 3c9f26410..735462e01 100644 --- a/tests/pipeline/test_base_merged_comment.py +++ b/tests/pipeline/test_base_merged_comment.py @@ -15,6 +15,7 @@ from agent_build_kit.pipeline.pr_replies import MARKER, own_posts from agent_build_kit.pipeline.unit_store import StoredUnit, UnitStore from agent_build_kit.pipeline.units import IN_REVIEW +from tests.factories import stored_unit from tests.forges.stand_in import FindingForge from tests.pipeline.test_retarget_retry import ( CHILD, @@ -129,6 +130,19 @@ def test_the_host_is_not_asked_about_a_unit_with_no_merged_base(tmp_path: Path) assert warn.asked == [] +def test_the_host_is_not_asked_about_a_unit_that_does_not_depend_on_the_merged_unit( + tmp_path: Path, +) -> None: + warn = Round(tmp_path) + other = "feature/9" + warn.store.upsert([stored_unit(other, change="feature")]) + warn.store.set_state(other, IN_REVIEW, pr=9, branch=f"spec/{other}") + + warn.run() + + assert warn.asked == [CHILD] + + def test_a_child_whose_host_base_is_unknown_gets_no_comment(tmp_path: Path) -> None: warn = Round(tmp_path) warn.bases.clear()