fix(agent): deterministic PR base — retarget agent-chosen base to the orchestrator's

The PR is opened by the agent's own `gh pr create` (prompt workflow), so its
`--base` is a model judgment call, not the orchestrator's. Live-caught on the
aws-samples#247 chain stress test (2026-07-18): a stacked child that branched off its
predecessor's branch opened its PR against `main` anyway ("this was based off
the chain-Y branch, let me open the PR against main"), and a root whose
detect_default_branch correctly returned `linear-vercel` was ALSO pointed at
`main`. Wrong base ⇒ the PR shows the whole default-branch divergence (100s of
files) instead of the child's real delta, and a stacked child merges onto the
wrong branch.

ensure_pr now reconciles an existing PR's base against setup.default_branch
(the orchestrator base_branch for a stacked child / the detected repo default
for a root) via `gh pr edit --base` — removing the agent's discretion without
forbidding it from opening the PR (keeps the agent-authored title/body).
Best-effort: a retarget failure WARNs, never fatal. Prompt hardened to tell the
agent not to substitute main/master even when the branch was cut elsewhere.

Tests: 4 new (retarget-on-mismatch, no-op-on-match, retarget-failure-warns,
create-path-uses-right-base); existing already-open test asserts no spurious
retarget.

Deferred: the diamond base + the reconciler's hardcoded 'main' defaultBranch
need a RepoConfig.default_branch field (server doesn't know the repo default);
tracked separately.

Author: isadeks

agent/src/post_hooks.py

@@ -398,6 +398,79 @@ def _note_unpushed_commits(repo_dir: str, branch: str, config: TaskConfig) -> No
         log("WARN", f"Failed to post un-pushed-commits note: {type(e).__name__}: {e}")
 
 
+def _reconcile_pr_base(repo_dir: str, branch: str, config: TaskConfig, expected_base: str) -> None:
+    """Deterministically retarget an existing PR onto ``expected_base``.
+
+    The PR is created by the AGENT (its own ``gh pr create`` in the prompt
+    workflow), so the ``--base`` it chose is a model judgment call, not the
+    orchestrator's. Live-caught on the #247 chain stress test (2026-07-18):
+    a stacked child that branched off its predecessor's branch STILL opened
+    its PR against ``main`` — the agent reasoned "this was based off the
+    chain-Y branch, let me open the PR against main" and even a root whose
+    ``detect_default_branch`` correctly returned ``linear-vercel`` was pointed
+    at ``main``. Wrong base ⇒ the PR shows the whole default-branch divergence
+    (100s of files) instead of the child's real delta, and a stacked child's
+    PR merges onto the wrong branch.
+
+    ``expected_base`` is ``setup.default_branch`` — which is the orchestrator's
+    ``base_branch`` for a stacked child (the predecessor's branch, or ``main``
+    for a diamond) and ``detect_default_branch`` for a root. This post-hook
+    reads the PR's current base and, if it disagrees, retargets it via
+    ``gh pr edit --base`` — removing the agent's discretion without forbidding
+    it from opening the PR (which keeps the agent-authored title/body).
+
+    Best-effort: any failure is logged, never fatal — a mis-based PR is a
+    presentation/merge-target defect, not a reason to fail the whole task.
+    """
+    try:
+        view = subprocess.run(
+            [
+                "gh",
+                "pr",
+                "view",
+                branch,
+                "--repo",
+                config.repo_url,
+                "--json",
+                "baseRefName",
+                "-q",
+                ".baseRefName",
+            ],
+            cwd=repo_dir,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        log("WARN", f"Could not read PR base to reconcile ({type(exc).__name__}) — leaving as-is")
+        return
+    if view.returncode != 0 or not view.stdout.strip():
+        # No PR / unreadable base — nothing to reconcile (creation path handles
+        # the no-PR case; a transient read error just leaves the base as-is).
+        return
+    current_base = view.stdout.strip()
+    if current_base == expected_base:
+        return
+    log(
+        "POST",
+        f"Retargeting PR base '{current_base}' → '{expected_base}' "
+        f"(deterministic; agent chose the wrong base)",
+    )
+    result = run_cmd(
+        ["gh", "pr", "edit", branch, "--repo", config.repo_url, "--base", expected_base],
+        label="reconcile-pr-base",
+        cwd=repo_dir,
+        check=False,
+    )
+    if result.returncode != 0:
+        stderr_msg = result.stderr.strip()[:200] if result.stderr else "(no stderr)"
+        log(
+            "WARN",
+            f"Failed to retarget PR base to '{expected_base}' (gh exit {result.returncode}): "
+            f"{stderr_msg} — PR remains based on '{current_base}'",
+        )
+
+
 def ensure_pr(
     config: TaskConfig,
     setup: RepoSetup,
@@ -491,6 +564,10 @@ def ensure_pr(
     if result.returncode == 0 and result.stdout.strip():
         pr_url = result.stdout.strip()
         log("POST", f"PR already exists: {pr_url}")
+        # The agent opened this PR and picked its own --base; correct it to the
+        # orchestrator-supplied / detected base if it disagrees (stacked-child
+        # + root wrong-base fix, 2026-07-18).
+        _reconcile_pr_base(repo_dir, branch, config, default_branch)
         return pr_url
 
     # Check if there are any commits on this branch beyond the default branch

agent/src/prompts/new_task.py

@@ -85,7 +85,12 @@
    - Any patterns or conventions you discovered about this repo
    - Suggestions for future tasks on this repo
 
-   Run:
+   Run this EXACTLY — the `--base` value is chosen for you (for a stacked \
+sub-issue it is the predecessor's branch so the PR shows only your delta; for \
+a normal task it is the repo default). Do NOT substitute a different base such \
+as `main`/`master` even if this branch was cut from another branch — targeting \
+the wrong base makes the PR show the whole branch divergence instead of your \
+change:
    ```
    gh pr create --repo {repo_url} --head {branch_name} --base {default_branch} --title "<type>(<module>): <description>" --body "<body>"
    ```

agent/tests/test_post_hooks.py

@@ -45,10 +45,18 @@ def __call__(self, cmd, **kwargs):
         return _cp()
 
 
-def _pr_view(url: str) -> _SubprocessRunRecorder:
-    """Recorder whose ``gh pr view`` returns *url* (other calls rc=0, empty)."""
+def _pr_view(url: str, base: str = "main") -> _SubprocessRunRecorder:
+    """Recorder for the two ``gh pr view`` shapes ensure_pr issues.
+
+    The URL query (``--json url``) returns *url*; the base query
+    (``--json baseRefName``, used by ``_reconcile_pr_base``) returns *base*.
+    Defaulting *base* to ``main`` matches ``_setup``'s default_branch so the
+    reconcile is a no-op unless a test opts into a mismatch.
+    """
 
     def responder(cmd):
+        if "view" in cmd and "baseRefName" in cmd:
+            return _cp(returncode=0, stdout=base + "\n")
         if "view" in cmd:
             return _cp(returncode=0, stdout=url + "\n")
         return _cp()
@@ -182,17 +190,24 @@ def _ensure_pushed(d, b):
 
 class TestEnsurePrCreate:
     def test_returns_existing_pr_when_already_open(self, monkeypatch):
-        # First `gh pr view` returns a URL -> short-circuit, no creation.
-        sub = _pr_view("https://github.com/o/r/pull/1")
+        # First `gh pr view` returns a URL -> short-circuit, no creation. The
+        # existing PR's base ("main") already matches default_branch, so the
+        # base reconcile is a no-op (no `gh pr edit`).
+        sub = _pr_view("https://github.com/o/r/pull/1", base="main")
         run_cmd = _RunCmdRecorder()
         monkeypatch.setattr(post_hooks.subprocess, "run", sub)
         monkeypatch.setattr(post_hooks, "run_cmd", run_cmd)
 
         url = post_hooks.ensure_pr(
-            _config(), _setup(), build_passed=True, lint_passed=True, strategy="create"
+            _config(),
+            _setup(default_branch="main"),
+            build_passed=True,
+            lint_passed=True,
+            strategy="create",
         )
         assert url == "https://github.com/o/r/pull/1"
         assert "create-pr" not in run_cmd.labels()
+        assert "reconcile-pr-base" not in run_cmd.labels()
 
     def test_no_commits_means_no_pr(self, monkeypatch):
         # pr view -> empty (no existing PR); git log diff -> empty (no commits).
@@ -249,3 +264,104 @@ def responder(cmd):
         assert "Resolves #55" in body
         assert "**PASS**" in body  # build passed
         assert "**FAIL**" in body  # lint failed
+
+
+class TestReconcilePrBase:
+    """The agent picks its own PR --base; ensure_pr corrects it deterministically
+    to setup.default_branch (the orchestrator's base for a stacked child / the
+    detected repo default for a root). Live-caught on the #247 chain: a stacked
+    child + a root both opened against a wrong 'main'."""
+
+    def test_retargets_when_base_mismatches(self, monkeypatch):
+        # Existing PR is based on 'main' but the stacked child's real base is
+        # the predecessor branch -> ensure_pr issues `gh pr edit --base <pred>`.
+        pred = "bgagent/task-x/abca-1-predecessor"
+        sub = _pr_view("https://github.com/o/r/pull/7", base="main")
+        run_cmd = _RunCmdRecorder()
+        monkeypatch.setattr(post_hooks.subprocess, "run", sub)
+        monkeypatch.setattr(post_hooks, "run_cmd", run_cmd)
+
+        url = post_hooks.ensure_pr(
+            _config(),
+            _setup(default_branch=pred),
+            build_passed=True,
+            lint_passed=True,
+            strategy="create",
+        )
+        assert url == "https://github.com/o/r/pull/7"
+        assert "reconcile-pr-base" in run_cmd.labels()
+        edit_cmd = run_cmd.cmd_for("reconcile-pr-base")
+        assert "edit" in edit_cmd
+        assert edit_cmd[edit_cmd.index("--base") + 1] == pred
+
+    def test_noop_when_base_matches(self, monkeypatch):
+        # PR base already == default_branch -> no `gh pr edit`.
+        sub = _pr_view("https://github.com/o/r/pull/7", base="develop")
+        run_cmd = _RunCmdRecorder()
+        monkeypatch.setattr(post_hooks.subprocess, "run", sub)
+        monkeypatch.setattr(post_hooks, "run_cmd", run_cmd)
+
+        url = post_hooks.ensure_pr(
+            _config(),
+            _setup(default_branch="develop"),
+            build_passed=True,
+            lint_passed=True,
+            strategy="create",
+        )
+        assert url == "https://github.com/o/r/pull/7"
+        assert "reconcile-pr-base" not in run_cmd.labels()
+
+    def test_retarget_failure_warns_and_is_not_fatal(self, monkeypatch):
+        # `gh pr edit` fails -> WARN naming the consequence, URL still returned.
+        pred = "bgagent/task-x/abca-1-predecessor"
+        sub = _pr_view("https://github.com/o/r/pull/7", base="main")
+        run_cmd = _RunCmdRecorder(returncodes={"reconcile-pr-base": 1})
+        monkeypatch.setattr(post_hooks.subprocess, "run", sub)
+        monkeypatch.setattr(post_hooks, "run_cmd", run_cmd)
+        warns: list[str] = []
+        monkeypatch.setattr(
+            post_hooks, "log", lambda lvl, msg: warns.append(msg) if lvl == "WARN" else None
+        )
+
+        url = post_hooks.ensure_pr(
+            _config(),
+            _setup(default_branch=pred),
+            build_passed=True,
+            lint_passed=True,
+            strategy="create",
+        )
+        assert url == "https://github.com/o/r/pull/7"
+        assert any("PR remains based on 'main'" in w for w in warns)
+
+    def test_reconcile_skipped_for_freshly_created_pr_path(self, monkeypatch):
+        # When the agent did NOT pre-create the PR, ensure_pr creates it with the
+        # correct --base directly; no separate reconcile needed (create path
+        # already uses default_branch). Guards against double-work.
+        def responder(cmd):
+            if "view" in cmd:
+                return _cp(returncode=1, stderr="no pr")
+            if "log" in cmd and "--reverse" in cmd:
+                return _cp(returncode=0, stdout="feat: x\n")
+            if "log" in cmd:
+                return _cp(returncode=0, stdout="feat: x\n\n---")
+            return _cp()
+
+        sub = _SubprocessRunRecorder(responder=responder)
+        run_cmd = _RunCmdRecorder(stdouts={"create-pr": "https://github.com/o/r/pull/8\n"})
+        monkeypatch.setattr(post_hooks, "ensure_pushed", lambda d, b: True)
+        monkeypatch.setattr(post_hooks.subprocess, "run", sub)
+        monkeypatch.setattr(post_hooks, "run_cmd", run_cmd)
+
+        pred = "bgagent/task-x/abca-1-predecessor"
+        url = post_hooks.ensure_pr(
+            _config(),
+            _setup(default_branch=pred),
+            build_passed=True,
+            lint_passed=True,
+            strategy="create",
+        )
+        assert url == "https://github.com/o/r/pull/8"
+        # create path used the right base; no post-creation reconcile fired.
+        create_cmd = run_cmd.cmd_for("create-pr")
+        assert create_cmd[create_cmd.index("--base") + 1] == pred
+        assert "reconcile-pr-base" not in run_cmd.labels()