feat: run GitHub review bots through Paperclip agents (#13717)

## Thinking Path

> - Paperclip manages agent work as tasks and runs.
> - GitHub chat brings repository conversations into those tasks.
> - A review bot needs the assigned agent, its authority, and governed
provider tools.
> - The existing channel connection did not supply that review workflow
or a complete setup journey.
> - This pull request adds GitHub App setup, account access, event
prompts, task-bound review tools, and exact-commit checks.
> - Operators can inspect each review through the same task, run, and
activity systems.

## Linked Issues or Issue Description

**Subsystem affected**

GitHub chat, governed connection tools, task execution, shared/database
contracts, and connector setup UI.

**Problem or motivation**

Operators need a GitHub review bot that runs their assigned Paperclip
agent. Mentions and PR events must preserve task ownership and requester
authority. Provider publication must use the bot App identity and
enforce the configured permissions.

**Proposed solution**

Extend the existing GitHub chat connector with resumable App onboarding,
linked-member and sponsored-guest access, editable event prompts, and
governed review operations. Validate structured assessments on the
server and compute a stable Paperclip Review check for the exact head
commit.

**Alternatives considered**

A separate review scheduler would duplicate Paperclip execution and
permissions. Reusing personal GitHub credentials would change the bot
identity and credential boundary.

**Roadmap alignment**

This extends the existing Connected Apps and governed-tool
infrastructure. The project owner requested and approved this design.
Related PR #8645 imports external Codex review feedback; this change
runs an assigned Paperclip agent and publishes its results through the
existing chat connector.

## What Changed

- Include the current Paperclip instance origin in the copied setup
prompt. Storybook uses its configured Paperclip origin; callback
parameters and URL credentials are excluded.

- Add a Claude/Codex copy button in the real setup and Storybook opening
step. Its detailed prompt asks four setup questions and guides
embedded-browser setup, verification, and optional required checks.
Clipboard failure exposes selectable instructions.
- Add a tutorial that explains why App installation, review scheduling,
and required checks are separate choices.

- Add manifest registration, an existing-App path, separate installation
and repository selection, repository refresh, and explicit account
confirmation.
- Add low-trust agent guidance, effective capability verification,
member selection, and explicit restricted guests with a sponsor.
- Add configurable PR events, prompts, repository overrides, rating
thresholds, and separate formal-review permissions.
- Give the assigned agent governed App tools to read PRs, comment, begin
an assessment, submit findings, and optionally submit a formal review.
- Bind review history, root PR events, and inline replies to ordinary
tasks. Deduplicate deliveries/findings and reject stale publication.
- Link check Details to the underlying task on the current trusted
hostname, or to Reviews before task creation.
- Add schema migration 0283, API contracts, production UI, and 49
interactive Storybook states.
- Repair local lease recovery. Keep the Cloud Dockerfile identical to
master; no provider-pack layer or runtime-default environment variable
is added.
- Retry only rolled-back wake-admission transactions after transient
endpoint-lock contention. A deterministic held-lock regression proves
one accepted wake.

## Verification

- Current head: `7ba761fe007bb798400d3e62346fa964f607f0f8`, rebased on
master `d9b3a5653e41f2ee5a1345b97c86a238f7a5c8e9`. Dockerfile has zero
diff against master. Final workspace typecheck and build passed. The new
PostgreSQL migration regression passed and preserves existing relation
and constraint identities after replay.
- Greptile reviewed this exact head at 5/5. There are zero unresolved
review threads and no merge conflicts.
- All current-head checks are green: 54 passed and two conditional
Storybook jobs skipped. This includes complete server/workspace test
suites, build, typechecks, policy checks, Runner suites, browser suites,
and security status. One timing-sensitive callback-ordering test passed
in isolation and its CI shard passed one retry. The duplicate local
full-suite run was stopped after CI completed; it is not counted as a
local full-suite pass.
- Before the final Slack rebase and migration renumbering, 186 focused
GitHub tests, 14 native bootstrap cases, token gates, and Storybook
build passed. The final rebase retained the new Slack communication
guidance.
- The embedded-browser setup test copied the full detailed prompt,
including the configured Paperclip instance URL. Desktop and narrow
layouts were checked. Component tests cover successful copying and
clipboard failure with selectable text and retry.
- Live local and hosted GitHub acceptance evidence refers to application
revision `cb703ac959876a07ebf3d7a295847f9f351eb6fc`. Real agent tasks
exercised issue mentions, automatic PR reviews, inline findings,
repeated mentions, task continuation, and failing-to-passing checks
after a push. The Storybook agent generated, built, and browser-rendered
pages; missing acceptance text failed, matching text passed, and broken
JSX produced an incomplete result.
- Live cases also covered independently disabled push events, prompt
injection, duplicate signed deliveries, rapid pushes, stale-result
rejection, finding deduplication, and restart recovery. Formal reviews
were denied while disabled and published only after explicit enablement.
Check Details links pointed to the underlying task on the trusted
hostname.
- Those hosted native Claude runs used the provider-pack layer now
removed from this PR. They do not prove native Claude works on the
standard Cloud image. A replacement hosted native Codex run is not yet
verified: the disposable QA tenant has only an Anthropic AI connection.
No new staging or production deployment was made for the packaging
removal.
- Required-check merge enforcement could not be tested because the
private disposable repository's GitHub plan rejected the rules
configuration. Published success/failure/incomplete check states were
verified directly.

## Risks

- Latest master allocated migration 0282 to Slack. The GitHub migration
is regenerated as 0283 with replay-safe table/index/constraint creation;
a PostgreSQL regression verifies existing relations and constraints are
preserved. Existing preview tenants remain subject to the fleet
migration-history compatibility preflight; no bypass is introduced.

- Migration 0283 adds company-scoped configuration, registration,
review, and publication records. Existing connections retain their
behavior until reviews/tools are enabled.
- Signed webhooks and expiring registration state remain required.
Hosted installations also need the companion narrow Cloud gateway
exemptions.
- Agent assessments can be incomplete or wrong. The server enforces
coverage/result structure, current-head publication, rating policy, and
separate formal-review permission; it does not replace code-review
judgment.
- No Cloud image packaging changes are included. Remote native
ACPX/Claude and OpenCode retain their existing operator-supplied
provider-pack prerequisite. Native Codex and Codex with managed MCP
tools do not require that pack. Earlier staging deployment evidence
refers to its stated revision, not this packaging-removal head.
Production rollout and merging remain outside this change.

## Model Used

OpenAI GPT-6 through Codex, with repository, code execution, API, and
embedded-browser tools. The exact serving model ID and context-window
size were not exposed by the environment.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

Author: cryppadotta

doc/connections/GITHUB-REVIEW-BOT.md

@@ -0,0 +1,130 @@
+# GitHub chat and review bots
+
+A GitHub bot belongs to one Paperclip agent. GitHub issues, pull requests, and
+review threads enter ordinary Paperclip tasks; the agent's runs, permissions,
+budget, and activity remain visible there. The Reviews page is a projection of
+assessments attached to those tasks, not a separate execution system.
+
+For a step-by-step explanation of mentions, automatic reviews, scores, and
+required GitHub checks, read
+[Understanding GitHub PR review bots](UNDERSTANDING-GITHUB-PR-REVIEW-BOTS.md).
+
+## Set up a bot
+
+1. Choose the permanent agent assignment. Prefer a
+   [low-trust review agent](https://docs.paperclip.ing/administration/trust-and-low-trust-review/)
+   with an isolated sandbox and a scoped task boundary. Standard-trust agents
+   show a warning; choosing one does not silently reduce their permissions.
+2. Make the instance reachable through public HTTPS, then create an App with
+   manifest registration or connect an existing App. Credentials are vaulted.
+3. Install the App on GitHub. Grant access only to the intended repositories.
+4. Refresh the repository list in Paperclip and enable the repositories this bot
+   should handle. GitHub installation access and Paperclip enablement are
+   separate controls. Use **Configure on GitHub** to change installation access,
+   then refresh again.
+5. Verify signed delivery, App identity, repository permissions, and the assigned
+   agent's effective tools/runtime separately. For existing Apps, add Contents
+   read, Pull requests write, and Checks write alongside chat permissions and
+   subscribe to pull-request events. Approve any installation permission upgrade.
+6. Choose your existing personal GitHub connection and explicitly confirm the
+   verified account identity. That connection links your identity; the bot uses
+   its own App credentials for agent tools and publication.
+7. Configure access, event prompts, review behavior, and publication permissions.
+   Save progress to resume later. The final mention test is optional.
+
+GitHub review bots use the existing agent runtime; this connector does not add
+provider software to the Cloud server image. Codex with managed MCP tools and
+the native Runner Codex backend do not require a server-side remote provider
+pack. Remote native ACPX (including Claude) and OpenCode currently require an
+operator-supplied, build-owned provider pack configured through
+`PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH`; the standard Cloud server image
+does not supply one. A pack installed in the sandbox alone does not satisfy
+that existing runtime requirement. Treat that provider setup as a separate
+Runner prerequisite, not an automatic connector installation step.
+
+Setup verification checks tool/runtime support and isolation; an actual test
+task is still required to prove that the chosen provider can execute in the
+selected environment.
+
+## Who can start work
+
+Linked members may be allowed together or selected individually. Teammates
+connect and confirm their own accounts; an administrator cannot assert someone
+else's identity by entering a username.
+
+To admit an unlinked GitHub person, explicitly add their verified GitHub account,
+choose an active sponsor, and use the restricted guest profile. Automatic reviews
+for that person are a separate choice. Guests receive no company membership or
+sponsor credentials. Authority is checked again before tool calls and
+publication, so revocation also affects queued or ongoing work.
+
+Automatic events use the configured responsible member. The PR author and
+webhook sender are recorded independently. Follow-ups preserve task ownership
+while checking the current requester's authority.
+
+## Mentions and pushes
+
+Use **mentions only** for reviews initiated by an authorized `@your-bot` request.
+Choose automatic reviews and enable **updated commits** to review new pushes.
+Opened, reopened, ready-for-review, and updated-commit events are independently
+configurable. Draft and bot-authored PRs are excluded by default. Settings can
+be overridden per enabled repository.
+
+An authorized mention can bypass automatic author/branch/label scheduling
+filters. It cannot bypass repository restrictions, excluded files, or access
+permissions. Ordinary discussion does not change a review score. Repeat review
+mentions and pushes continue the existing task; inline replies return to the
+task owning that thread.
+
+Event prompts supplement the agent's instructions. Repository content and PR
+prose are untrusted input and cannot change tool authority or publication policy.
+The execution records the configuration revision and event context used.
+
+## Assessments, checks, and formal reviews
+
+The agent reads through task-bound bot tools, explicitly begins an assessment,
+and submits the reviewed commit, findings, rationale, and coverage. Paperclip
+validates the result and computes the **Paperclip Review** check. The default
+threshold is 5/5; choose 1–5 or report-only as needed.
+
+| Score | Assessment rubric |
+| --- | --- |
+| 0 | No usable assessment; explain what prevented evaluation. |
+| 1 | Critical defects make the change unsafe to ship. |
+| 2 | Major defects require substantial correction. |
+| 3 | Meaningful defects require correction before merging. |
+| 4 | Minor concerns remain; explain impact and remaining risk. |
+| 5 | No actionable defects found within the stated coverage and limitations. |
+
+Incomplete coverage cannot pass. Filtering which findings become inline comments
+does not remove them from the assessment. A new head requires a new assessment;
+old runs cannot publish over the latest head. One current summary is updated in
+place, with history and task/run links retained. Stable finding keys prevent
+duplicate inline comments on repeated reviews.
+
+The check's **Details** link opens its Paperclip task on the current instance
+hostname, or the connector's Reviews page when no task has been created yet.
+
+Formal **APPROVE** and **REQUEST_CHANGES** are separate governed tools, each off
+by default. Enabling either does not automatically perform it. A score of 5/5
+alone never approves a PR.
+
+To enforce the rating at merge time, configure GitHub branch protection or a
+ruleset to require **Paperclip Review**, selecting this bot App as the source
+where supported. Paperclip does not change repository rules. GitHub account and
+repository plan restrictions may limit required-check enforcement. If automatic
+execution is disallowed, a gated head requests an authorized manual review.
+
+## Hosted ingress
+
+Cloud proxies only `POST /api/chat-webhooks/:publicId/github` and the narrow
+`GET /api/chat-github/manifest/callback` registration callback without browser
+login. The instance verifies the untouched webhook body and GitHub signature;
+registration uses expiring, single-use user/company/origin-bound state.
+Installation return, configuration, and identity confirmation remain
+authenticated. URLs use the trusted current vanity hostname, with explicit
+webhook-ingress overrides preserved.
+
+Existing chat connections do not gain review execution or broader permissions
+until explicitly configured. GitHub.com and UI-managed settings are the initial
+scope; cross-repository indexing and auto-fix are not included.