[sentry-junior]

Part of #2488 (track 3, scenario C1).

When a pull request that Junior opened is ready to merge, a notice Review item now appears on the review desk for the person who asked for it. The notice tells them to merge the pull request, or to say why not. It closes by itself when the pull request merges, closes, or is no longer ready. "Changes requested" does not add an item.

Plugin contract

packages/junior-plugin-api/src/review-items.ts adds a small provider-neutral contract. Plugins get it as RouteRegistrationHookContext.reviewItems:

interface PluginConversationReviewItems {
  forConversation(conversationId: string): PluginReviewItems;
}
interface PluginReviewItems {
  upsert(notice: PluginReviewNotice): Promise<void>; // add, or replace the open item with the key
  close(input: { dedupeKey: string; reason: string; status: "done" | "dismissed" }): Promise<void>;
}
interface PluginReviewNotice {
  assigneeIdentityIds: string[];
  body: string;
  dedupeKey: string; // at most one open item per key, per plugin
  subject?: { id: string; title?: string; url?: string };
  title: string;
}

Core puts this in packages/junior/src/chat/review-items/plugin.ts, built on review-items/store.ts. Core scopes the dedupe key to the plugin and takes visibility from the Conversation. It resolves Identities to Users and keeps the rule that a private item can only go to a participant. After each change it calls the show function that app setup passes to getPluginRoutes (today the Slack card sync), so review item code imports no Slack code. A plugin change sends no messages to linked Conversations. A plugin notice never counts as an item that needs a person (reviewItemNeedsUser). Core has no GitHub names or logic.

The plugin: dedupe key prefix belongs to plugins. An agent cannot add an item with that prefix, and it cannot change or close an item that a plugin added (review-items/access.ts, tools/review-items.ts). Only the plugin or a person can. The review items README and the updateReviewItem description list "the plugin that added it closes it" as a close path.

How readiness is decided (GitHub plugin)

packages/junior-github/src/webhooks/pull-request-ready.ts handles these webhooks for Junior pull requests:

• pull_request: closed, converted_to_draft, ready_for_review, reopened, synchronize
• pull_request_review: submitted, dismissed
• check_suite: completed

For each one, loadPullRequestMergeState reads the current state from GitHub with a read-only installation token. The result does not depend on the model. A pull request is ready to merge when all of these are true:

• Open and not a draft: from GET /pulls/{n}.
• GitHub can merge it: mergeable_state is clean. This covers required reviews, checks, commit statuses, and conflicts. GitHub computes this value after a change. When it is still unknown after a second read, the plugin changes nothing, and a later webhook decides.
• Approved: we read every page of reviews and take each reviewer's latest review that is not a comment or pending. At least one of these must be APPROVED, and none can be CHANGES_REQUESTED.

When the pull request becomes ready, the plugin adds the notice for the opener, in the Conversation where they asked. The dedupe key is the pull request. When it merges, the plugin closes the notice as done. When it closes or is no longer ready, the plugin closes the notice as dismissed. The requester record now also stores the opener's Conversation, and the create pull request tool fills it in.

State and webhooks that arrive together

Migration 0010 adds these columns to the stored pull request:

• ready_to_merge_at: the notice was added. Repeat webhooks add no second notice. A notice that a person closed does not come back until the pull request is ready again. The value changes only after the notice changes, so after a failure the next webhook tries again.
• ready_sync_requests, ready_sync_id, ready_sync_at: one webhook at a time checks a pull request. A webhook that arrives during a check adds 1 to ready_sync_requests and stops. The webhook that runs the check reads GitHub again until no new request came in, also when a check fails. ready_sync_id names the check. A check older than one minute no longer blocks others.

No database connection or lock stays open during the GitHub and review desk calls. A notice failure is logged and does not fail the webhook.

Checks

• pnpm typecheck, pnpm lint
• packages/junior-github: pnpm exec vitest run (21 files, 259 tests pass). tests/pull-request-ready.test.ts covers webhooks that arrive during a check, including during a failed close, and an approval on the second page of reviews.
• core: pnpm exec vitest run tests/integration/plugin-review-items.test.ts tests/integration/review-item-tools.test.ts tests/integration/review-item-access.test.ts tests/unit/plugins/agent-hooks.test.ts
• core: tests/integration/api/review-items and tests/integration/slack/review-item-card-webhook.test.ts also pass (64 tests in total with the files above)
• Rebased on main after ref(review-desk): Deliver every Review item change through one path #2481, fix(review-desk): Use one rule for items that need a person #2503, and fix(review-desk): Close Review items that no agent can act on #2506.

via @dcramer.

--

View Session [Sentry]

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
junior-docs	Ready	Preview	Nov 1, 2026 10:01pm UTC

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ebd0eac. Configure here.}