claude-dev-env 8.19.2 → 8.21.0

package/bin/install.mjs

@@ -25,6 +25,10 @@ import {
     pruneManagedPermissionsFromSettings,
     retiredManagedPermissions,
 } from './merge_managed_permissions.mjs';
+import {
+    mergeMissingSettingsDefaults,
+    settingsDefaultsFromPackageSettings,
+} from './merge_settings_defaults.mjs';
 import {
     SKIPPED_SOURCE_ENTRY_NAMES,
     SKIPPED_SOURCE_FILE_EXTENSIONS,
@@ -2176,6 +2180,26 @@ function mergeManagedPermissions() {
     return { ...mergeOutcome, removedCount: pruneOutcome.removedCount };
 }
 
+/**
+ * Add each package setting default that ~/.claude/settings.json lacks.
+ *
+ * @returns {{addedKeys: string[]}}
+ */
+function mergePackageSettingsDefaults() {
+    const packageSettingsPath = join(PACKAGE_ROOT, SETTINGS_FILE_NAME);
+    if (!existsSync(packageSettingsPath)) return { addedKeys: [] };
+    const settingsDefaults = settingsDefaultsFromPackageSettings(
+        JSON.parse(readFileSync(packageSettingsPath, 'utf8')),
+    );
+    const settingsPath = join(CLAUDE_HOME, SETTINGS_FILE_NAME);
+    const settings = loadClaudeSettingsObject(settingsPath);
+    const mergeOutcome = mergeMissingSettingsDefaults(settings, settingsDefaults);
+    if (mergeOutcome.addedKeys.length > 0) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
+    }
+    return mergeOutcome;
+}
+
 /**
  * Merge two path lists into one, keyed on `comparisonKeyForPath`, with the
  * current run's spelling winning a collision.
@@ -2864,6 +2888,11 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         );
     }
 
+    const settingsDefaultsMerge = mergePackageSettingsDefaults();
+    if (settingsDefaultsMerge.addedKeys.length > 0) {
+        console.log(`  Settings: added ${settingsDefaultsMerge.addedKeys.join(', ')}`);
+    }
+
     const agentsHubSource = join(PACKAGE_ROOT, 'AGENTS.md');
     if (existsSync(agentsHubSource)) {
         const agentsHubDest = join(AGENTS_HOME, 'AGENTS.md');

package/bin/install.settings-defaults.test.mjs

@@ -21,6 +21,10 @@ import {
     mergeManagedPermissionsIntoSettings,
     pruneManagedPermissionsFromSettings,
 } from './merge_managed_permissions.mjs';
+import {
+    mergeMissingSettingsDefaults,
+    settingsDefaultsFromPackageSettings,
+} from './merge_settings_defaults.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PACKAGE_SETTINGS_PATH = join(PACKAGE_ROOT, 'settings.json');
@@ -251,3 +255,39 @@ test('sandbox uninstall removes only package-owned permission entries and keeps
         rmSync(sandboxHome, { recursive: true, force: true });
     }
 });
+
+test('package settings.json publishes the advisor model default', () => {
+    const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
+    assert.deepEqual(settingsDefaultsFromPackageSettings(packageSettings), { advisorModel: 'fable' });
+});
+
+test('a missing default is added and a user-set value is kept', () => {
+    const emptySettings = {};
+    assert.deepEqual(mergeMissingSettingsDefaults(emptySettings, { advisorModel: 'fable' }), {
+        addedKeys: ['advisorModel'],
+    });
+    assert.equal(emptySettings.advisorModel, 'fable');
+    const userSettings = { advisorModel: 'sonnet' };
+    assert.deepEqual(mergeMissingSettingsDefaults(userSettings, { advisorModel: 'fable' }), {
+        addedKeys: [],
+    });
+    assert.equal(userSettings.advisorModel, 'sonnet');
+});
+
+test('install adds advisorModel when missing and keeps a user choice on rerun', () => {
+    const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
+    try {
+        const firstRun = runInstallerInSandbox(sandboxHome);
+        assert.equal(firstRun.status, 0, firstRun.stderr);
+        const settingsPath = join(sandboxHome, '.claude', 'settings.json');
+        assert.equal(JSON.parse(readFileSync(settingsPath, 'utf8')).advisorModel, 'fable');
+        const userChoice = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        userChoice.advisorModel = 'sonnet';
+        writeFileSync(settingsPath, JSON.stringify(userChoice, null, 4) + '\n');
+        const secondRun = runInstallerInSandbox(sandboxHome);
+        assert.equal(secondRun.status, 0, secondRun.stderr);
+        assert.equal(JSON.parse(readFileSync(settingsPath, 'utf8')).advisorModel, 'sonnet');
+    } finally {
+        rmSync(sandboxHome, { recursive: true, force: true });
+    }
+});

package/bin/merge_settings_defaults.mjs

@@ -0,0 +1,43 @@
+/**
+ * Merge package-owned scalar setting defaults into a settings object.
+ *
+ * Every top-level key in the package settings.json other than the managed
+ * lists (`permissions`) is a default. Install adds a default only when the
+ * user settings lack that key, so a value the user already set stays as is.
+ */
+
+export const MANAGED_LIST_SETTING_KEYS = Object.freeze(['permissions']);
+
+/**
+ * Read the setting defaults from a package settings source object.
+ *
+ * @param {Record<string, unknown> | null | undefined} packageSettings
+ * @returns {Record<string, unknown>}
+ */
+export function settingsDefaultsFromPackageSettings(packageSettings) {
+    if (!packageSettings || typeof packageSettings !== 'object' || Array.isArray(packageSettings)) {
+        return {};
+    }
+    return Object.fromEntries(
+        Object.entries(packageSettings).filter(
+            ([settingKey]) => !MANAGED_LIST_SETTING_KEYS.includes(settingKey),
+        ),
+    );
+}
+
+/**
+ * Add each default whose key the target settings lack.
+ *
+ * @param {Record<string, unknown>} targetSettings Mutated in place.
+ * @param {Record<string, unknown>} settingsDefaults
+ * @returns {{addedKeys: string[]}}
+ */
+export function mergeMissingSettingsDefaults(targetSettings, settingsDefaults) {
+    const addedKeys = [];
+    for (const [settingKey, defaultValue] of Object.entries(settingsDefaults)) {
+        if (Object.hasOwn(targetSettings, settingKey)) continue;
+        targetSettings[settingKey] = defaultValue;
+        addedKeys.push(settingKey);
+    }
+    return { addedKeys };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.19.2",
+    "version": "8.21.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/agent-merges-its-own-green-pull-request.md

@@ -24,7 +24,7 @@ One command prints the verdict:
 python packages/claude-dev-env/scripts/agent_merge_check.py <owner>/<name> <number>
 ```
 
-It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check still running or red, and for an open review thread. It exits 2 when the state could not be read.
+It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check still running or red, for a head the merge queue ejected for failed checks, and for an open review thread. It exits 2 when the state could not be read.
 
 Each hold reason names its own repair, and each repair belongs to the agent:
 
@@ -35,6 +35,7 @@ Each hold reason names its own repair, and each repair belongs to the agent:
 | A required check is red | Read the failing check, fix it, push |
 | A check is red or still running | Fix it, or wait for it, then read the verdict again |
 | A review thread is open | Answer it, push the fix, resolve the thread |
+| Ejected from the merge queue for failed checks on this head | Read the merge_group run, fix the failure, push, then read the verdict again |
 | The pull request is a draft | Mark it ready once the checks pass |
 
 ## When a gate elsewhere holds the merge command

package/rules/review-closure-is-a-check.md

@@ -26,6 +26,8 @@ It prints `CLOSED` and exits 0 when every finding on the head is answered. It pr
 | A blocking `Claude Approvals` row | A push, which moves the head the check reports on |
 | A top-level comment on the pull request | A later top-level comment from the driving account |
 
+A review bot rewrites its summary comment on each pass. Its edit leaves an answered summary closed, because each new finding it has arrives as a review thread or a new comment. An edit from a person reopens the comment.
+
 A red circle marks a finding a review states as blocking, so resolution in silence leaves it open. The reply says what changed or why the finding stands, and the reviewer reads it beside the diff.
 
 The driving account is the one that opened the pull request. Where the agent comments under a second login, `--driver-login <login>` names it, repeatably.

package/scripts/agent_merge_check.py

@@ -32,7 +32,9 @@ from dataclasses import dataclass
 
 from dev_env_scripts_constants.agent_merge_check_constants import (
     ACCEPT_HEADER,
+    ALL_HEAD_COMMIT_NODE_KEYS,
     ALL_HOLD_REASONS_BY_STATE,
+    ALL_MERGE_QUEUE_REMOVAL_NODE_KEYS,
     ALL_PASSING_CHECK_CONCLUSIONS,
     ALL_OUTDATED_KEYS,
     ALL_RESOLVED_KEYS,
@@ -58,12 +60,16 @@ from dev_env_scripts_constants.agent_merge_check_constants import (
     CHECK_RUNS_KEY,
     COMBINED_STATUS_ENDPOINT_TEMPLATE,
     COMMAND_DESCRIPTION,
+    COMMIT_KEY,
+    COMMITTED_DATE_KEY,
     COMPARE_ENDPOINT_TEMPLATE,
     CONTENT_TYPE_HEADER,
     CONTEXT_KEY,
+    CREATED_AT_KEY,
     DRAFT_HOLD_REASON,
     DRAFT_KEY,
     ERROR_EXIT_CODE,
+    FAILED_CHECKS_REMOVAL_REASON,
     FAILING_REQUIRED_CHECKS_HOLD_TEMPLATE,
     GITHUB_ACCEPT_TYPE,
     GITHUB_API_ROOT,
@@ -74,6 +80,9 @@ from dev_env_scripts_constants.agent_merge_check_constants import (
     INTEGRATION_ID_KEY,
     JSON_CONTENT_TYPE,
     MERGE_EXIT_CODE,
+    MERGE_QUEUE_EJECTION_HOLD_TEMPLATE,
+    MERGE_QUEUE_REMOVAL_PAGE_SIZE,
+    MERGE_QUEUE_REMOVAL_QUERY,
     MERGE_QUEUE_RULE_TYPE,
     MERGE_VERDICT_LABEL,
     MERGEABLE_STATE_BLOCKED,
@@ -95,6 +104,7 @@ from dev_env_scripts_constants.agent_merge_check_constants import (
     QUERY_KEY,
     READY_DETAIL,
     REF_KEY,
+    REMOVAL_REASON_KEY,
     REQUIRED_CHECK_SEPARATOR,
     REQUIRED_CHECK_STATE_TEMPLATE,
     REQUIRED_STATUS_CHECKS_KEY,
@@ -181,6 +191,7 @@ def hold_reason(
     all_pull_request_fields: Mapping[str, object],
     unresolved_thread_count: int,
     blocked_evidence: BlockedEvidence | None = None,
+    is_ejected_from_merge_queue: bool = False,
 ) -> str | None:
     """Return why this pull request stays open, or None when it may merge.
 
@@ -190,11 +201,14 @@ def hold_reason(
         unresolved_thread_count: How many review threads are open on it.
         blocked_evidence: What was read behind a ``blocked`` merge state, or
             None when nothing was read.
+        is_ejected_from_merge_queue: Whether the merge queue ejected the
+            current head for failed checks.
 
     Returns:
-        The reason text for a draft, for a merge state other than clean, and
-        for an open review thread. None when the pull request is ready for
-        the agent that drives it to merge it.
+        The reason text for a draft, for a merge state other than clean, for
+        a head the merge queue ejected, and for an open review thread. None
+        when the pull request is ready for the agent that drives it to merge
+        it.
     """
     if all_pull_request_fields.get(DRAFT_KEY):
         return DRAFT_HOLD_REASON
@@ -206,11 +220,27 @@ def hold_reason(
             merge_state,
             UNKNOWN_STATE_HOLD_TEMPLATE.format(state=merge_state),
         )
+    if is_ejected_from_merge_queue:
+        return MERGE_QUEUE_EJECTION_HOLD_TEMPLATE.format(
+            base=_optional_nested_field(all_pull_request_fields, BASE_KEY, REF_KEY),
+            number=all_pull_request_fields.get(NUMBER_KEY),
+        )
     if unresolved_thread_count > 0:
         return UNRESOLVED_THREADS_HOLD_TEMPLATE.format(count=unresolved_thread_count)
     return None
 
 
+def _optional_nested_field(
+    all_fields: Mapping[str, object],
+    outer_key: str,
+    inner_key: str,
+) -> object:
+    all_inner_fields = all_fields.get(outer_key)
+    if not isinstance(all_inner_fields, Mapping):
+        return None
+    return all_inner_fields.get(inner_key)
+
+
 def required_contexts(all_rules: Sequence[object]) -> tuple[RequiredContext, ...]:
     """Collect each status check the branch rules require, once, in order.
 
@@ -406,6 +436,27 @@ def count_unresolved_threads(all_thread_records: Sequence[object]) -> int:
     )
 
 
+def _is_ejected_on_head(
+    all_removal_records: Sequence[object],
+    head_committed_at: str,
+) -> bool:
+    """Report whether a ``failed_checks`` removal is newer than the head.
+
+    A commit that lands after the merge queue ejected the pull request
+    carries a fix the queue has not seen yet, so an older removal holds
+    nothing back.
+    """
+    all_failed_check_times = [
+        str(each_removal.get(CREATED_AT_KEY))
+        for each_removal in all_removal_records
+        if isinstance(each_removal, Mapping)
+        and each_removal.get(REMOVAL_REASON_KEY) == FAILED_CHECKS_REMOVAL_REASON
+    ]
+    return (
+        bool(all_failed_check_times) and max(all_failed_check_times) > head_committed_at
+    )
+
+
 def _any_flag(all_thread_fields: Mapping[str, object], all_keys: Sequence[str]) -> bool:
     return any(all_thread_fields.get(each_key) for each_key in all_keys)
 
@@ -648,14 +699,20 @@ def _thread_records_over_rest(
     return document if isinstance(document, list) else None
 
 
-def _thread_query_payload(owner: str, name: str, number: int) -> dict[str, object]:
+def _pull_request_query_payload(
+    query: str,
+    page_size: int,
+    slug: str,
+    number: int,
+) -> dict[str, object]:
+    owner, _, name = slug.partition(SLUG_SEPARATOR)
     return {
-        QUERY_KEY: UNRESOLVED_THREAD_QUERY,
+        QUERY_KEY: query,
         VARIABLES_KEY: {
             OWNER_VARIABLE: owner,
             NAME_VARIABLE: name,
             NUMBER_VARIABLE: number,
-            PAGE_SIZE_VARIABLE: REVIEW_THREAD_PAGE_SIZE,
+            PAGE_SIZE_VARIABLE: page_size,
         },
     }
 
@@ -665,11 +722,12 @@ def _read_unresolved_thread_count_over_graphql(
     number: int,
     token: str,
 ) -> int:
-    owner, _, name = slug.partition(SLUG_SEPARATOR)
     document = _request_json(
         GITHUB_GRAPHQL_ENDPOINT,
         token,
-        _thread_query_payload(owner, name, number),
+        _pull_request_query_payload(
+            UNRESOLVED_THREAD_QUERY, REVIEW_THREAD_PAGE_SIZE, slug, number
+        ),
     )
     all_thread_records = functools.reduce(
         functools.partial(_field_at, document),
@@ -687,6 +745,59 @@ def _field_at(document: object, all_fields: object, key: str) -> object:
     return all_fields.get(key)
 
 
+def read_merge_queue_ejection(slug: str, number: int, token: str) -> bool:
+    """Read whether the merge queue ejected the pull request's current head.
+
+    Only GraphQL reports why a pull request left the merge queue. A
+    repository with no merge queue reports no removal events.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        True when a ``failed_checks`` removal is newer than the head commit.
+
+    Raises:
+        MergeCheckError: The query failed, or answered with another shape.
+    """
+    document = _request_json(
+        GITHUB_GRAPHQL_ENDPOINT,
+        token,
+        _pull_request_query_payload(
+            MERGE_QUEUE_REMOVAL_QUERY, MERGE_QUEUE_REMOVAL_PAGE_SIZE, slug, number
+        ),
+    )
+    return _is_ejected_on_head(
+        _list_along(document, ALL_MERGE_QUEUE_REMOVAL_NODE_KEYS),
+        _head_committed_at(document),
+    )
+
+
+def _list_along(document: object, all_keys: Sequence[str]) -> list[object]:
+    all_records = functools.reduce(
+        functools.partial(_field_at, document), all_keys, document
+    )
+    if not isinstance(all_records, list):
+        raise MergeCheckError(str(document))
+    return all_records
+
+
+def _head_committed_at(document: object) -> str:
+    all_head_commits = _list_along(document, ALL_HEAD_COMMIT_NODE_KEYS)
+    if not all_head_commits:
+        raise MergeCheckError(str(document))
+    head_committed_at = functools.reduce(
+        functools.partial(_field_at, document),
+        (COMMIT_KEY, COMMITTED_DATE_KEY),
+        all_head_commits[-1],
+    )
+    if not isinstance(head_committed_at, str):
+        raise MergeCheckError(str(document))
+    return head_committed_at
+
+
 def read_settled_pull_request(
     slug: str,
     number: int,
@@ -741,6 +852,9 @@ def main(all_arguments: Sequence[str]) -> int:
         unresolved_thread_count = read_unresolved_thread_count(
             parsed.slug, parsed.number, token
         )
+        is_ejected_from_merge_queue = read_merge_queue_ejection(
+            parsed.slug, parsed.number, token
+        )
     except MergeCheckError as failure:
         print(failure, file=sys.stderr)
         return ERROR_EXIT_CODE
@@ -753,7 +867,10 @@ def main(all_arguments: Sequence[str]) -> int:
         except MergeCheckError as failure:
             print(failure, file=sys.stderr)
     reason = hold_reason(
-        all_pull_request_fields, unresolved_thread_count, blocked_evidence
+        all_pull_request_fields,
+        unresolved_thread_count,
+        blocked_evidence,
+        is_ejected_from_merge_queue,
     )
     print(verdict_line(parsed.slug, all_pull_request_fields, reason))
     return HOLD_EXIT_CODE if reason else MERGE_EXIT_CODE

package/scripts/dev_env_scripts_constants/agent_merge_check_constants.py

@@ -117,6 +117,13 @@ UNKNOWN_STATE_HOLD_TEMPLATE = (
 UNRESOLVED_THREADS_HOLD_TEMPLATE = (
     "{count} review thread(s) are open. Answer each one and resolve it."
 )
+MERGE_QUEUE_EJECTION_HOLD_TEMPLATE = (
+    "The merge queue ejected this head for failed checks, and no commit has "
+    "landed since. Read the merge_group run for the "
+    "gh-readonly-queue/{base}/pr-{number}-<sha> branch, fix the failure, and "
+    "push before you enqueue it again."
+)
+FAILED_CHECKS_REMOVAL_REASON = "failed_checks"
 
 MERGE_VERDICT_LABEL = "MERGE"
 HOLD_VERDICT_LABEL = "HOLD"
@@ -148,6 +155,19 @@ query($owner: String!, $name: String!, $number: Int!, $pageSize: Int!) {
   }
 }
 """
+MERGE_QUEUE_REMOVAL_PAGE_SIZE = 100
+MERGE_QUEUE_REMOVAL_QUERY = """
+query($owner: String!, $name: String!, $number: Int!, $pageSize: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      commits(last: 1) { nodes { commit { committedDate } } }
+      timelineItems(last: $pageSize, itemTypes: [REMOVED_FROM_MERGE_QUEUE_EVENT]) {
+        nodes { ... on RemovedFromMergeQueueEvent { createdAt reason } }
+      }
+    }
+  }
+}
+"""
 QUERY_KEY = "query"
 VARIABLES_KEY = "variables"
 OWNER_VARIABLE = "owner"
@@ -166,5 +186,25 @@ ALL_THREAD_NODE_KEYS = (
     REVIEW_THREADS_KEY,
     NODES_KEY,
 )
+COMMITS_KEY = "commits"
+COMMIT_KEY = "commit"
+COMMITTED_DATE_KEY = "committedDate"
+TIMELINE_ITEMS_KEY = "timelineItems"
+CREATED_AT_KEY = "createdAt"
+REMOVAL_REASON_KEY = "reason"
+ALL_MERGE_QUEUE_REMOVAL_NODE_KEYS = (
+    DATA_KEY,
+    REPOSITORY_KEY,
+    PULL_REQUEST_KEY,
+    TIMELINE_ITEMS_KEY,
+    NODES_KEY,
+)
+ALL_HEAD_COMMIT_NODE_KEYS = (
+    DATA_KEY,
+    REPOSITORY_KEY,
+    PULL_REQUEST_KEY,
+    COMMITS_KEY,
+    NODES_KEY,
+)
 ALL_RESOLVED_KEYS = ("isResolved", "is_resolved", "resolved")
 ALL_OUTDATED_KEYS = ("isOutdated", "is_outdated", "outdated")

package/scripts/dev_env_scripts_constants/review_closure_constants.py

@@ -131,6 +131,12 @@ NUMBER_KEY: str = "number"
 USER_KEY: str = "user"
 """Field carrying the account that opened a pull request."""
 
+USER_TYPE_KEY: str = "type"
+"""Field on a REST user naming whether the account is a person or a bot."""
+
+BOT_USER_TYPE: str = "Bot"
+"""The user type GitHub reports for an app account such as a review bot."""
+
 SHORT_SHA_LENGTH: int = 7
 """How much of a commit identifier the verdict line prints."""
 

package/scripts/review_closure_model.py

@@ -13,10 +13,14 @@ and the approvals conclusion, and name what waits.
     thread: a red circle, resolved in silence   -> open
     top-level: a bot comment, no agent comment  -> open
     top-level: a bot comment, then an agent one -> closed
-    top-level: the bot edits after that reply   -> open
+    top-level: the bot edits after that reply   -> closed
+    top-level: a person edits after that reply  -> open
 
 A red circle marks a finding a review states as blocking, so resolution alone
 leaves it open. The reply says what changed, or why the finding stands.
+A review bot rewrites its summary comment on each pass, and any new finding it
+has arrives as a review thread or a new comment, so its edit alone reopens
+nothing.
 """
 
 from __future__ import annotations
@@ -34,6 +38,7 @@ from dev_env_scripts_constants.review_closure_constants import (
     APPROVALS_CHECK_NAME,
     APPROVALS_OPEN_REASON,
     AUTHOR_LOGIN_KEY,
+    BOT_USER_TYPE,
     CHECK_RUN_CONCLUSION_KEY,
     CHECK_RUN_NAME_KEY,
     CLOSED_DETAIL,
@@ -58,6 +63,7 @@ from dev_env_scripts_constants.review_closure_constants import (
     UNNAMED_THREAD_SUBJECT,
     UPDATED_AT_KEY,
     USER_KEY,
+    USER_TYPE_KEY,
     VERDICT_LINE_TEMPLATE,
 )
 
@@ -86,6 +92,7 @@ class TopLevelComment:
 
     identifier: object
     author_login: str
+    is_bot: bool
     created_at: datetime
     updated_at: datetime
     url: str
@@ -212,7 +219,8 @@ def top_level_finding(
     """
     if comment.author_login in all_driver_logins:
         return None
-    if latest_driver_time is not None and comment.updated_at <= latest_driver_time:
+    last_counted_at = comment.created_at if comment.is_bot else comment.updated_at
+    if latest_driver_time is not None and last_counted_at <= latest_driver_time:
         return None
     return OpenFinding(
         subject=comment.url,
@@ -228,15 +236,18 @@ def top_level_findings(
 
     The driving agent answers a top-level comment by posting a top-level
     comment of its own. Its latest one answers every comment last touched
-    before it, and a comment edited after it waits again.
+    before it. A person's comment edited after it waits again. A bot's edit
+    leaves its comment answered, since a bot posts each new finding as a
+    review thread or a new comment.
 
     Args:
         all_comments: The top-level comments on the pull request.
         all_driver_logins: The logins whose comments count as the answer.
 
     Returns:
-        One finding per comment from another account that was posted or
-        edited after the driving agent's latest top-level comment.
+        One finding per comment from another account posted after the
+        driving agent's latest top-level comment, and one per person's
+        comment edited after it.
     """
     all_listed_comments = tuple(all_comments)
     latest_driver_time = latest_driver_comment_time(
@@ -424,6 +435,7 @@ def parse_top_level_comment(
     return TopLevelComment(
         identifier=all_comment_fields.get(COMMENT_IDENTIFIER_KEY),
         author_login=_comment_author_login(all_comment_fields),
+        is_bot=_is_bot_author(all_comment_fields),
         created_at=datetime.fromisoformat(str(all_comment_fields.get(CREATED_AT_KEY))),
         updated_at=datetime.fromisoformat(str(all_comment_fields.get(UPDATED_AT_KEY))),
         url=str(all_comment_fields.get(HTML_URL_KEY) or ""),
@@ -477,6 +489,14 @@ def _parse_comment(all_comment_fields: Mapping[str, object]) -> ReviewComment:
     )
 
 
+def _is_bot_author(all_comment_fields: Mapping[str, object]) -> bool:
+    all_author_fields = all_comment_fields.get(USER_KEY)
+    return (
+        isinstance(all_author_fields, Mapping)
+        and all_author_fields.get(USER_TYPE_KEY) == BOT_USER_TYPE
+    )
+
+
 def _comment_author_login(all_comment_fields: Mapping[str, object]) -> str:
     for each_key in ALL_COMMENT_AUTHOR_KEYS:
         all_author_fields = all_comment_fields.get(each_key)

package/scripts/test_agent_merge_check.py

@@ -290,6 +290,11 @@ def test_a_ready_pull_request_exits_zero(monkeypatch: pytest.MonkeyPatch) -> Non
         "read_unresolved_thread_count",
         lambda slug, number, token: 0,
     )
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_merge_queue_ejection",
+        lambda slug, number, token: False,
+    )
     assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 0
 
 
@@ -305,6 +310,11 @@ def test_a_held_pull_request_exits_one(monkeypatch: pytest.MonkeyPatch) -> None:
         "read_unresolved_thread_count",
         lambda slug, number, token: 0,
     )
+    monkeypatch.setattr(
+        agent_merge_check,
+        "read_merge_queue_ejection",
+        lambda slug, number, token: False,
+    )
     assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 1
 
 
@@ -319,6 +329,7 @@ def test_an_unreadable_pull_request_exits_two(
     assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 2
 
 
+HEAD_COMMITTED_AT = "2026-09-26T16:00:00Z"
 PULL_REQUEST_4922_HEAD_SHA = "06bc18a1a8761a16e92c1419693a42f22dd4ae7c"
 REQUIRED_CHECK_APP_ID = 15368
 PULL_REQUEST_4922 = {
@@ -386,11 +397,28 @@ def _github_answers(
             return {"statuses": all_statuses or []}
         if "/compare/" in parsed.path:
             return {"behind_by": behind_by, "ahead_by": 1}
+        if parsed.path.endswith("/graphql"):
+            return _merge_queue_document([])
         raise AssertionError(url)
 
     return _answer
 
 
+def _merge_queue_document(all_removals: list[dict[str, object]]) -> object:
+    return {
+        "data": {
+            "repository": {
+                "pullRequest": {
+                    "commits": {
+                        "nodes": [{"commit": {"committedDate": HEAD_COMMITTED_AT}}]
+                    },
+                    "timelineItems": {"nodes": all_removals},
+                }
+            }
+        }
+    }
+
+
 def _run_main(
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -610,3 +638,147 @@ def test_blocked_hold_reason_names_every_unmet_required_check() -> None:
     )
     assert "Ruff (failure), Tip Local green (missing)" in reason
     assert "behind" not in reason
+
+
+QUEUED_PULL_REQUEST = {
+    "number": 1442,
+    "draft": False,
+    "mergeable_state": "clean",
+    "base": {"ref": "main"},
+    "head": {"sha": "ab845eb6945650055ebe852312a9057b9f067d6a"},
+}
+
+
+def _removal(created_at: str, reason: str) -> dict[str, object]:
+    return {"createdAt": created_at, "reason": reason}
+
+
+def _merge_queue_answers(
+    all_removals: list[dict[str, object]],
+) -> object:
+    def _answer(url: str, token: str, all_payload_fields: object) -> object:
+        if url.endswith("/pulls/1442"):
+            return QUEUED_PULL_REQUEST
+        if url.endswith("/ccr/review_threads"):
+            return []
+        if url.endswith("/graphql"):
+            return _merge_queue_document(all_removals)
+        raise AssertionError(url)
+
+    return _answer
+
+
+def _run_queued_main(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    all_removals: list[dict[str, object]],
+) -> tuple[int, str]:
+    monkeypatch.setenv("GH_TOKEN", "token")
+    monkeypatch.setattr(
+        agent_merge_check, "_request_json", _merge_queue_answers(all_removals)
+    )
+    exit_code = agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"])
+    return exit_code, capsys.readouterr().out
+
+
+def test_a_head_ejected_from_the_merge_queue_for_failed_checks_holds(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code, line = _run_queued_main(
+        monkeypatch,
+        capsys,
+        [
+            _removal("2026-09-26T15:09:20Z", "failed_checks"),
+            _removal("2026-09-26T17:11:35Z", "failed_checks"),
+        ],
+    )
+    assert exit_code == 1
+    assert line.startswith(HOLD_VERDICT_LABEL)
+    assert "merge queue" in line
+    assert "failed checks" in line
+    assert "merge_group" in line
+    assert "gh-readonly-queue/main/pr-1442-<sha>" in line
+    assert "before you enqueue it again" in line
+
+
+def test_a_fix_pushed_after_the_merge_queue_ejection_clears_the_hold(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code, line = _run_queued_main(
+        monkeypatch,
+        capsys,
+        [_removal("2026-09-26T15:09:20Z", "failed_checks")],
+    )
+    assert exit_code == 0
+    assert line.startswith(MERGE_VERDICT_LABEL)
+
+
+def test_a_manual_merge_queue_removal_does_not_hold(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code, line = _run_queued_main(
+        monkeypatch,
+        capsys,
+        [
+            _removal("2026-09-26T15:09:20Z", "failed_checks"),
+            _removal("2026-09-26T17:58:17Z", "manual"),
+        ],
+    )
+    assert exit_code == 0
+    assert line.startswith(MERGE_VERDICT_LABEL)
+
+
+def test_a_repository_with_no_merge_queue_removal_may_merge(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code, line = _run_queued_main(monkeypatch, capsys, [])
+    assert exit_code == 0
+    assert line.startswith(MERGE_VERDICT_LABEL)
+
+
+def test_a_merge_queue_answer_of_another_shape_exits_two(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    routed_answer = _merge_queue_answers([])
+
+    def _answer(url: str, token: str, all_payload_fields: object) -> object:
+        if url.endswith("/graphql"):
+            return {"errors": [{"message": "Bad credentials"}]}
+        return routed_answer(url, token, all_payload_fields)
+
+    monkeypatch.setenv("GH_TOKEN", "token")
+    monkeypatch.setattr(agent_merge_check, "_request_json", _answer)
+    assert agent_merge_check.main(["jl-cmd/claude-dev-env", "1442"]) == 2
+    assert capsys.readouterr().out == ""
+
+
+@pytest.mark.parametrize(
+    ("all_removals", "expected_ejection"),
+    [
+        ([_removal("2026-09-26T17:11:35Z", "failed_checks")], True),
+        ([_removal("2026-09-26T15:09:20Z", "failed_checks")], False),
+        ([_removal("2026-09-26T17:58:17Z", "manual")], False),
+        ([], False),
+    ],
+)
+def test_read_merge_queue_ejection_compares_failed_checks_removals_to_the_head(
+    monkeypatch: pytest.MonkeyPatch,
+    all_removals: list[dict[str, object]],
+    expected_ejection: bool,
+) -> None:
+    monkeypatch.setattr(
+        agent_merge_check,
+        "_request_json",
+        lambda url, token, all_payload_fields: _merge_queue_document(all_removals),
+    )
+    assert (
+        agent_merge_check.read_merge_queue_ejection(
+            "jl-cmd/claude-dev-env", 1442, "token"
+        )
+        is expected_ejection
+    )

package/scripts/tests/test_review_closure.py

@@ -139,6 +139,7 @@ def should_print_the_url_of_a_waiting_top_level_comment(
     bot_summary = model.TopLevelComment(
         identifier=1,
         author_login="qodo-merge-pro[bot]",
+        is_bot=True,
         created_at=posted,
         updated_at=posted,
         url=summary_url,

package/scripts/tests/test_review_closure_model.py

@@ -21,6 +21,7 @@ from dev_env_scripts_constants.review_closure_constants import (
 
 DRIVING_AGENT = frozenset({"claude[bot]"})
 REVIEW_BOT = "qodo-merge-pro[bot]"
+REVIEWER = "maintainer"
 
 
 def thread(
@@ -313,10 +314,12 @@ def top_level_comment(
     posted_minute: int,
     edited_minute: int | None = None,
     url: str = BOT_SUMMARY_URL,
+    is_bot: bool = True,
 ) -> model.TopLevelComment:
     return model.TopLevelComment(
         identifier=posted_minute,
         author_login=author_login,
+        is_bot=is_bot,
         created_at=at_minute(posted_minute),
         updated_at=at_minute(posted_minute if edited_minute is None else edited_minute),
         url=url,
@@ -355,9 +358,9 @@ def should_close_every_earlier_comment_with_one_driver_comment() -> None:
     assert model.top_level_findings(all_comments, DRIVING_AGENT) == ()
 
 
-def should_reopen_a_bot_comment_edited_after_the_driver_reply() -> None:
+def should_reopen_a_person_comment_edited_after_the_driver_reply() -> None:
     all_comments = (
-        top_level_comment(REVIEW_BOT, 1, edited_minute=5),
+        top_level_comment(REVIEWER, 1, edited_minute=5, is_bot=False),
         top_level_comment("claude[bot]", 2),
     )
 
@@ -366,6 +369,15 @@ def should_reopen_a_bot_comment_edited_after_the_driver_reply() -> None:
     assert [each.subject for each in all_findings] == [BOT_SUMMARY_URL]
 
 
+def should_keep_a_bot_summary_closed_when_edited_after_the_driver_reply() -> None:
+    all_comments = (
+        top_level_comment(REVIEW_BOT, 1, edited_minute=5),
+        top_level_comment("claude[bot]", 2),
+    )
+
+    assert model.top_level_findings(all_comments, DRIVING_AGENT) == ()
+
+
 def should_leave_a_bot_comment_posted_after_the_driver_open() -> None:
     all_comments = (
         top_level_comment("claude[bot]", 1),
@@ -403,9 +415,28 @@ def should_close_a_bot_comment_last_edited_at_the_driver_time() -> None:
     assert model.top_level_finding(comment, DRIVING_AGENT, at_minute(4)) is None
 
 
-def should_open_a_bot_comment_edited_after_the_driver_time() -> None:
+def should_open_a_person_comment_edited_after_the_driver_time() -> None:
+    comment = top_level_comment(REVIEWER, 1, edited_minute=5, is_bot=False)
+
+    assert model.top_level_finding(
+        comment, DRIVING_AGENT, at_minute(4)
+    ) == model.OpenFinding(
+        subject=BOT_SUMMARY_URL,
+        reason=TOP_LEVEL_OPEN_REASON_TEMPLATE.format(author=REVIEWER),
+    )
+
+
+def should_close_a_bot_comment_posted_before_and_edited_after_the_driver_time() -> (
+    None
+):
     comment = top_level_comment(REVIEW_BOT, 1, edited_minute=5)
 
+    assert model.top_level_finding(comment, DRIVING_AGENT, at_minute(4)) is None
+
+
+def should_open_a_bot_comment_posted_after_the_driver_time() -> None:
+    comment = top_level_comment(REVIEW_BOT, 5)
+
     assert model.top_level_finding(
         comment, DRIVING_AGENT, at_minute(4)
     ) == model.OpenFinding(
@@ -426,7 +457,7 @@ def should_read_a_top_level_comment_record() -> None:
     comment = model.parse_top_level_comment(
         {
             "id": 1,
-            "user": {"login": REVIEW_BOT},
+            "user": {"login": REVIEW_BOT, "type": "Bot"},
             "created_at": "2026-09-26T12:01:00Z",
             "updated_at": "2026-09-26T12:05:00Z",
             "html_url": BOT_SUMMARY_URL,
@@ -434,3 +465,17 @@ def should_read_a_top_level_comment_record() -> None:
     )
 
     assert comment == top_level_comment(REVIEW_BOT, 1, edited_minute=5)
+
+
+def should_read_a_person_top_level_comment_record() -> None:
+    comment = model.parse_top_level_comment(
+        {
+            "id": 1,
+            "user": {"login": REVIEWER, "type": "User"},
+            "created_at": "2026-09-26T12:01:00Z",
+            "updated_at": "2026-09-26T12:05:00Z",
+            "html_url": BOT_SUMMARY_URL,
+        }
+    )
+
+    assert comment == top_level_comment(REVIEWER, 1, edited_minute=5, is_bot=False)

package/settings.json

@@ -3,5 +3,6 @@
         "allow": [
             "WebFetch(domain:docs.github.com)"
         ]
-    }
+    },
+    "advisorModel": "fable"
 }