@cursor/bdk 0.2.24 → 0.2.25

package/docs/guides/pagerduty.md

@@ -0,0 +1,341 @@
+---
+title: "PagerDuty"
+description: "Respond to PagerDuty incidents: investigate a page, follow it through acknowledgement and resolution, and ignore your own actions."
+---
+
+# PagerDuty agents
+
+A PagerDuty agent wakes when an incident triggers, investigates it, and
+writes what it found back to the incident. `pagerdutyChannel()` receives
+PagerDuty's v3 webhooks, verifies them, and keeps every later event for
+the same incident in one session, so the agent sees an acknowledgement,
+a note, or a responder's reply in the context of the investigation it
+already started. Every setting has a default read from a well-known secret, so
+the channel needs no configuration beyond its hooks; see
+[Connect](#connect) for the variables.
+
+## Investigate a new incident
+
+When an incident triggers, the agent starts a turn with the incident's
+title, service, urgency, and link. It reads whatever the investigation
+needs, and with `deliverReplies: true` its reply is posted as a note on
+the incident, where the person on call already looks.
+
+```ts
+// bot/channels/pagerduty.ts
+import { defaultPagerDutyAuth, pagerdutyChannel } from "@cursor/bdk/channels/pagerduty";
+
+export default pagerdutyChannel({
+  deliverReplies: true,
+  onIncident: (ctx, event) => {
+    if (event.eventType !== "incident.triggered") {
+      return null;
+    }
+    return {
+      // `auth` starts a model turn running as the event's PagerDuty actor.
+      auth: defaultPagerDutyAuth(ctx),
+      message: `Investigate PagerDuty incident #${event.incident.number}: ${event.incident.title}`,
+      context: [`Service: ${event.incident.service?.summary ?? "unknown"}`],
+    };
+  },
+});
+```
+
+Reply notes are off unless you set `deliverReplies: true`, so the channel
+writes nothing to PagerDuty on its own. An agent that writes to PagerDuty
+through its own path, such as a service that audits each write, leaves it
+off and posts only what it chooses, from `events` or `ctx.pagerduty`.
+
+With `deliverReplies: true`, the channel posts each completed reply as a
+note on the session's incident, and a short note if a turn fails, using
+the `PAGERDUTY_TOKEN` secret. The note goes to the incident in the
+verified event's state, so the model never chooses which incident it
+writes to. Eval runs and agents without a token post nothing. Nothing is
+posted until the channel knows the agent's own PagerDuty user (see
+[Ignore your own actions](#ignore-your-own-actions)), because each note
+comes back as a webhook event that only the echo skip keeps from starting
+another turn. Handlers you write in `events` replace the built-in ones.
+
+Hooks also get `ctx.pagerduty`, a REST client with the channel's
+credentials, for reads and writes of their own:
+
+```ts
+onIncident: async (ctx, event) => {
+  const incident = await ctx.pagerduty.getIncident(event.incident.id);
+  // …
+},
+```
+
+Hosted, the agent also declares PagerDuty's API host and the token:
+
+```ts
+// bot/agent.ts
+import { defineAgent } from "@cursor/bdk";
+
+export default defineAgent({
+  architecture: "v2",
+  hosting: {
+    egressDomains: ["api.pagerduty.com"],
+    secretNames: ["PAGERDUTY_TOKEN"],
+  },
+});
+```
+
+## Follow the incident in one session
+
+People act on an incident while the agent investigates: someone
+acknowledges it, adds a note, pulls in a responder, or resolves it.
+Return a dispatch for those events too, and each one arrives in the
+session that is already working on the incident, with the earlier
+findings in context.
+
+```ts
+onIncident: (ctx, event) => {
+  const followUps = ["incident.acknowledged", "incident.reassigned", "incident.resolved"];
+  if (event.eventType !== "incident.triggered" && !followUps.includes(event.eventType)) {
+    return null;
+  }
+  return {
+    auth: defaultPagerDutyAuth(ctx),
+    message: `${event.eventType} by ${ctx.agent?.summary ?? "PagerDuty"}`,
+  };
+},
+onNote: (ctx, note) => {
+  return {
+    auth: defaultPagerDutyAuth(ctx),
+    message: `Note on the incident: ${note.content}`,
+  };
+},
+```
+
+Add these to the same `pagerdutyChannel()` declaration as the
+investigation handler.
+
+## Ignore your own actions
+
+PagerDuty sends the agent's own changes back as webhook events: the
+note it posted, or an acknowledgement or resolve made through its
+PagerDuty user. The channel acknowledges those events without running a
+hook or starting a turn. The same action by a person is still delivered.
+
+The channel finds the agent's user in this order, on each delivery:
+
+1. The `selfUserIds` option, when you pass one. Nothing below is used.
+2. The `PAGERDUTY_USER_ID` secret: one PagerDuty user id.
+3. The user `PAGERDUTY_TOKEN` acts as, which PagerDuty reports at
+   `GET /users/me`.
+
+When none of these names a user, echo skip is off. `bdk deploy` warns
+while neither `PAGERDUTY_USER_ID` nor `PAGERDUTY_TOKEN` is set, and the
+agent logs a warning when its token names no single user.
+
+Inference depends on the kind of token:
+
+| `PAGERDUTY_TOKEN` | Inferred user |
+| --- | --- |
+| User token REST API key | The key's own user |
+| OAuth user token (Classic User OAuth or Scoped OAuth), written as `Bearer <token>` | The user who authorized the app |
+| General access (account-level) REST API key | The user whose email is exactly `PAGERDUTY_FROM_EMAIL`, if set |
+| Scoped OAuth app token (client credentials) | The user whose email is exactly `PAGERDUTY_FROM_EMAIL`, if set |
+
+PagerDuty serves
+[`GET /users/me`](https://developer.pagerduty.com/api-reference/0b6f8b0c3e8d1-get-the-current-user)
+only to a user-level API key or a token from an OAuth flow, not to an
+account-level key. An app token
+[acts as the app](https://docs.pagerduty.com/developer/private-apps),
+not as a user. With either, the channel looks up `PAGERDUTY_FROM_EMAIL`,
+the `From` user the token writes as, through `GET /users?query=` and uses
+the one user whose email matches exactly. The inferred id is kept in the
+agent's memory for an hour per token, never in agent storage, and an
+unresolved answer is retried after five minutes. Hosted, the lookup needs
+`api.pagerduty.com` (or your `PAGERDUTY_API_BASE_URL` host) in
+`hosting.egressDomains`, the same entry write-backs need.
+
+A read-only agent with no token sets the id directly:
+
+```bash
+bdk secrets set incident-responder PAGERDUTY_USER_ID
+```
+
+`PAGERDUTY_USER_ID` holds one id because a deployment has one token
+and so acts as one PagerDuty user. To skip several users, or to keep the
+id in code, pass `selfUserIds`:
+
+```ts
+export default pagerdutyChannel({
+  selfUserIds: ["PBOT001"],
+  onIncident: (ctx) => ({ auth: defaultPagerDutyAuth(ctx) }),
+});
+```
+
+`selfUserIds: { secretName: "OTHER_NAME" }` reads one id from another
+secret and never falls back to inference.
+
+## Events
+
+Each hook receives one family of v3 events:
+
+| Hook | Events |
+| --- | --- |
+| `onIncident` | `incident.triggered`, `.acknowledged`, `.unacknowledged`, `.escalated`, `.reassigned`, `.delegated`, `.resolved`, `.reopened`, `.priority_updated`, `.incident_type.changed` |
+| `onNote` | `incident.annotated` |
+| `onResponder` | `incident.responder.added`, `incident.responder.replied` |
+| `onEvent` | Everything else, such as status updates and workflow events |
+
+Without `onIncident`, a triggered or reopened incident starts a turn and
+other lifecycle events are acknowledged. Notes, responder events, and
+the rest are acknowledged until you add their hook. Each hook returns
+one of three decisions:
+
+| Return | What happens |
+| --- | --- |
+| `{ auth }` | Start or continue a model turn as the event's actor |
+| `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
+| `null` | Skip the event |
+
+## Incident affinity
+
+Every event for one incident joins one session, keyed on the incident
+id. Lifecycle events carry the incident, and notes and responder events
+name it by reference, so all of them reach the same session.
+
+A re-trigger after a resolve is a new PagerDuty incident, so it starts a
+new session. `ctx.incidentKey` carries the dedup key of the alert that
+opened an incident (its `incident_key`, set per alert by a Datadog
+monitor, a Sentry issue, or a Grafana rule), for an agent that wants to
+recall what it found the last time the same alert fired.
+
+## Connect
+
+Create a v3 webhook subscription in PagerDuty for the services that
+should wake the agent, and point it at
+`https://<your-host>/<slug>/v1/channels/pagerduty`. Then set the
+channel's secrets on the deployment. Locally the same names are
+environment variables.
+
+| Variable | Used for | Override |
+| --- | --- | --- |
+| `PAGERDUTY_WEBHOOK_SECRET` | Verifying `X-PagerDuty-Signature`. Hosted, the platform checks it before any compute starts and answers a bad delivery with `401` | `webhookSecret: { secretName }` |
+| `PAGERDUTY_USER_ID` | Skipping the agent's own actions: its PagerDuty user id. Optional when `PAGERDUTY_TOKEN` names a user | `selfUserIds: [ids]` or `{ secretName }` |
+| `PAGERDUTY_TOKEN` | Reply notes (with `deliverReplies: true`), `ctx.pagerduty`, and inferring the agent's user: a REST API key, or an OAuth token as `Bearer <token>` | `token: { secretName }` |
+| `PAGERDUTY_FROM_EMAIL` | The `From` user PagerDuty requires for writes made with an account-level key or app token, and the user inferred for those tokens | `from: { secretName }` |
+| `PAGERDUTY_API_BASE_URL` | The REST host, such as `https://api.eu.pagerduty.com`. Defaults to `https://api.pagerduty.com` | `apiBaseUrl` |
+
+Set `token`, `from`, and `apiBaseUrl` on `pagerdutyChannel()`; they cover
+reply notes, `ctx.pagerduty`, and inference. `createPagerDutyClient()`
+takes the same options for code outside the channel.
+
+```bash
+bdk deploy --dir . --slug incident-responder
+bdk secrets set incident-responder PAGERDUTY_WEBHOOK_SECRET PAGERDUTY_TOKEN
+bdk secrets list incident-responder
+```
+
+`bdk deploy` warns until `PAGERDUTY_WEBHOOK_SECRET` is set, and until
+either `PAGERDUTY_USER_ID` or `PAGERDUTY_TOKEN` is. The next delivery
+uses a new value without another deploy.
+
+### Several subscriptions
+
+PagerDuty gives each webhook subscription its own signing secret, so an
+agent fed by several subscriptions (one per service, say) needs all of
+them. Put them in `PAGERDUTY_WEBHOOK_SECRET`, one per line:
+
+```text
+<signing secret of subscription 1>
+<signing secret of subscription 2>
+```
+
+A delivery is admitted when any `v1=` signature in its
+`X-PagerDuty-Signature` header matches any line. Each line is trimmed,
+blank lines are ignored, and a value without a line break is one secret,
+used as-is. The value holds at most 32 secrets. Past that, every delivery
+is rejected rather than checked against only some of them.
+
+Keep the list in a file, since `bdk secrets list` never shows values,
+and set it from stdin, which keeps the line breaks:
+
+```bash
+bdk secrets set incident-responder PAGERDUTY_WEBHOOK_SECRET < pagerduty-webhook-secrets.txt
+```
+
+Rotate by adding before removing. Add the new secret as a line before
+PagerDuty starts signing with it, for example before creating the
+replacement subscription. Remove the old line only once nothing signs
+with the old secret, for example after deleting the subscription it
+replaced. While both are live, a delivery signed with either secret
+verifies, including one whose header carries both signatures. Removing
+the old line first rejects those deliveries until the new one is added.
+
+The same format works for every `hmacSignatureAuth()` secret, including
+`GITHUB_WEBHOOK_SECRET` and `BITBUCKET_WEBHOOK_SECRET`. It needs
+`@cursor/bdk` 0.2.25 or later. Earlier versions check the signature again
+in the agent with the whole value as one secret, so they reject every
+delivery once the value has a second line.
+
+Only signature checks read the value as a list. Everywhere else it is
+used whole: a `sharedSecretAuth()` header compares the entire value, and
+a `${NAME}` template in an MCP connection's `headers` would put the line
+breaks into the header. Keep a list secret for webhook signing only.
+
+Until `PAGERDUTY_WEBHOOK_SECRET` is set, the route accepts only local
+traffic: loopback deliveries under `bdk dev`, nothing in production.
+
+## Test locally
+
+`bdk pagerduty replay` posts synthesized v3 deliveries for one incident
+to the running agent, in order. With `PAGERDUTY_WEBHOOK_SECRET` unset,
+`bdk dev` admits them unsigned from loopback; with it set, replay signs
+them the way PagerDuty does:
+
+```bash
+bdk dev &
+bdk pagerduty replay --events triggered,acknowledged,annotated,resolved \
+  --comment "Rolled back the 09:30 deploy."
+```
+
+The trigger comes from PagerDuty itself, and the later events come from a
+person, so each one joins the session the trigger started. Pass an
+incident id to start another session, `--dry-run` to print the bodies,
+or `--out fixtures/pagerduty` to save them as fixtures for
+[evals](../evals.md). `bdk pagerduty events` lists the channels and the
+events each accepts.
+
+To post a real delivery saved from the webhook's delivery log, sign it
+with the secret:
+
+```bash
+export PAGERDUTY_WEBHOOK_SECRET=local-test-secret
+bdk dev &
+
+body=fixtures/pagerduty/incident-triggered.json
+signature=$(openssl dgst -sha256 -hmac "$PAGERDUTY_WEBHOOK_SECRET" -hex < "$body" | awk '{print $NF}')
+curl -X POST http://127.0.0.1:3000/v1/channels/pagerduty \
+  -H 'content-type: application/json' \
+  -H "x-pagerduty-signature: v1=$signature" \
+  --data-binary @"$body"
+```
+
+Set `event.agent.id` in a saved body to the agent's own user id to see
+the delivery skipped as an echo.
+
+## Practices
+
+- Write back from host code with the incident in channel state or
+  `ctx`, never from an incident id the model produced.
+
+- Make sure the agent knows its own user before it acts on incidents, so
+  its own notes and resolves do not wake it again: a user-level token, a
+  `PAGERDUTY_FROM_EMAIL` with an account-level key, or `PAGERDUTY_USER_ID`.
+
+- Scope the webhook subscription to the services the agent responds to;
+  every delivery it sends reaches the channel.
+
+## Related
+
+- [Channels reference](../reference/channels.md): channel hooks,
+  dispatch decisions, and session behavior
+- [Webhooks and custom channels](./webhooks.md): direct webhook auth
+  and reply delivery
+- [Evals](../evals.md): turn saved PagerDuty payloads into regression
+  fixtures

package/docs/reference/channels.md

@@ -166,7 +166,7 @@ returns `401`.
 | `loopbackOnly()` | Any loopback TCP peer, including local relays that carry forwarding headers |
 | `bearerAuth(tokenOrVerify)` | A matching bearer token, or a token accepted by the verifier |
 | `sharedSecretAuth({ header, secret })` | A header matching the named environment or deployment secret |
-| `hmacSignatureAuth({ header, secret, prefix? })` | A hex HMAC-SHA256 signature over the raw body using the named secret |
+| `hmacSignatureAuth({ header, secret, prefix?, separator? })` | A hex HMAC-SHA256 signature over the raw body using the named secret. With `separator`, any of several signatures in the header. A secret holding one value per line verifies under any of them (at most 32, `@cursor/bdk` 0.2.25 or later) |
 | `allowAll()` | Every caller as an anonymous principal |
 | `publicEndpoint()` | Every caller on this custom channel; managed hosting also exposes the route without an alias token |
 
@@ -193,6 +193,7 @@ author their own chain, and `--allow-anonymous` swaps it for
 | `@cursor/bdk/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](../guides/github.md) |
 | `@cursor/bdk/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](../guides/gitlab.md) |
 | `@cursor/bdk/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](../guides/bitbucket.md) |
+| `@cursor/bdk/channels/pagerduty` | `pagerdutyChannel()` | PagerDuty v3 incident webhooks. Replies post as incident notes only with `deliverReplies: true`. See [PagerDuty](../guides/pagerduty.md) |
 | `@cursor/bdk/channels/deployments` | `deploymentsChannel()` | Deployment events filtered by source, environment, or event name |
 
 For other platforms like Discord or Teams, use the authored

package/docs/reference/cli.md

@@ -1024,6 +1024,33 @@ follow the GitHub replay contract.
 
 See [Bitbucket](../guides/bitbucket.md) for Cloud and Data Center setup.
 
+### Test PagerDuty webhooks {#pagerduty}
+
+```text
+bdk pagerduty replay [incident-id]
+  [--events a,b,c | '*'] [--comment <body>]
+  [--dir <path>] [--slug <slug>] [--channel <id>]
+  [--url <url>] [--host <host>] [--port <n>]
+  [--secret <secret>] [--dry-run] [--out <dir>] [--json]
+bdk pagerduty events [--dir <path>] [--host <host>] [--port <n>] [--json]
+```
+
+| Subcommand | Contract |
+| --- | --- |
+| `replay` | Synthesize v3 webhook bodies for one incident and post them, in order, to matching channels. The default event is `incident.triggered`; `'*'` selects every declared event replay supports. |
+| `events` | List discovered PagerDuty channel URLs and event types. |
+
+Replay supports `incident.triggered`, `.acknowledged`, `.annotated`,
+`.escalated`, `.resolved`, and `.reopened`, by full name or by action alone
+(`resolved`). It needs no PagerDuty account. The incident id defaults to
+`PREPLAY1`, and `--comment` is the note body for `annotated`. `--secret`
+defaults to `PAGERDUTY_WEBHOOK_SECRET`, signing with its first line when it
+lists several; without either the deliveries are unsigned, which `bdk dev`
+admits from loopback. `--dry-run` and `--out`
+follow the GitHub replay contract.
+
+See [PagerDuty](../guides/pagerduty.md) for channel setup.
+
 ## Environment variables
 
 Credential resolution follows this order: `--api-key`, `CURSOR_API_KEY`,

package/docs/reference/tools.md

@@ -71,6 +71,7 @@ export default defineTool({
 | --- | --- |
 | `ctx.toolCallId` | The call id, matching the `actions.requested` / `action.result` stream events |
 | `ctx.session` | Read-only session info: id, channel, mode, auth |
+| `ctx.approvedBy` | For a `needsApproval` tool, the auth of whoever approved this call, in the same shape as `ctx.session.auth`. On Slack, `attributes.user_id` is the person who clicked Approve, who can differ from the person who started the thread. Unset when the call needed no approval |
 | `ctx.workspaceDir` | The session's workspace directory |
 | `ctx.stateRoot` | The agent's durable state root, shared across every session |
 | `ctx.host` | Shared host services (see below) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/bdk",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "Build, test, and deploy BDK bots and agents as code on Cursor's agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -141,6 +141,13 @@
       "import": "./dist/channels/bitbucket/index.js",
       "default": "./dist/channels/bitbucket/index.js"
     },
+    "./channels/pagerduty": {
+      "anysphere-source": "./src/channels/pagerduty/index.ts",
+      "bun": "./dist/channels/pagerduty/index.js",
+      "types": "./dist/channels/pagerduty/index.d.ts",
+      "import": "./dist/channels/pagerduty/index.js",
+      "default": "./dist/channels/pagerduty/index.js"
+    },
     "./channels/deployments": {
       "anysphere-source": "./src/channels/deployments/index.ts",
       "types": "./dist/channels/deployments/index.d.ts",
@@ -365,12 +372,12 @@
     "vitepress-plugin-mermaid": "^2.0.17",
     "vitest": "5.0.3",
     "yaml": "^2.4.2",
-    "zod": "^3.25.0",
+    "zod": "4.6.5",
     "zustand": "^5.0.9",
     "@anysphere/agent-exec": "1.0.0",
-    "@anysphere/context": "1.0.0",
     "@anysphere/agent-store-sync": "1.0.0",
     "@anysphere/proto": "1.0.0",
+    "@anysphere/context": "1.0.0",
     "@anysphere/ui": "1.0.0"
   },
   "scripts": {

package/skills/migrate-v2/SKILL.md

@@ -393,5 +393,5 @@ After the deploy is running:
   `bdk session <ses_...> --prod --slug <slug>` until the latest run
   finishes.
 
-The [deploy skill](../deploy/SKILL.md) covers deploys with an attached
+The deploy skill (`skills/deploy/SKILL.md`) covers deploys with an attached
 service account.

package/skills/otel/SKILL.md

@@ -22,6 +22,9 @@ Public surface (use one of these):
 2. `serve(dir, { otel: { … } })`. `otel: false` disables env and
    authored config.
 
+Metrics use delta temporality by default. For Grafana Cloud, set
+`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative`.
+
 `bot/otel.ts` is factory-only. Import `defineOtel` from
 `@cursor/bdk/internal/otel` only in a Cursor factory agent.
 A customer agent uses the environment variables above.
@@ -47,9 +50,10 @@ Hosted agents:
 | Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
 
 Prompt text and tool payloads stay off the wire unless you set
-`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`. A failed tool
-span status includes a short failure reason. BDK keeps its own
-exporters when the process already has a provider.
+`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`. A failed tool's
+span status and its `action.result` log include a short failure
+reason. BDK keeps its own exporters when the process already has a
+provider.
 
 ## Custom metrics
 

package/templates/agentic-owners/README.md

@@ -51,7 +51,12 @@ policies:
 `self_review: true` lets a listed `user:` owner's own PRs auto-approve
 (team membership is not resolved with repo-scoped credentials, so team
 ownership stays fail-closed for authors). `global_exclusions` (root
-policy only) opts paths out entirely.
+policy only) opts paths out entirely. `global_overrides` (root policy
+only, `self_review: true` required) let their owners self-review a file
+whose advisory winner they do not own. They add no owners and leave a file
+with no owner unowned. They leave exclusions, always-approve, hard, and
+notify winners unchanged, and they skip a `skip_teams` team or a
+`skip_paths` path.
 
 ## What the agent does
 

package/templates/agentic-owners/bot/lib/owners/decision.ts

@@ -140,16 +140,42 @@ export function authorOwnsRule(
   return rule.users.some((user) => normalizeHandle(user) === handle);
 }
 
+/**
+ * Whether the author may clear `rule` by self-review. A merged override
+ * records who may self-review in `selfReviewTeams` / `selfReviewUsers`:
+ * the winner's owners when that rule sets `self_review`, and the override's
+ * owners when the override sets it.
+ */
+export function authorMaySelfReview(
+  rule: AgenticOwnersPathRule,
+  author: ApprovalAuthor | undefined,
+): boolean {
+  if (!rule.selfReview) {
+    return false;
+  }
+  if (rule.selfReviewTeams === undefined && rule.selfReviewUsers === undefined) {
+    return authorOwnsRule(rule, author);
+  }
+  return authorOwnsRule(
+    {
+      ...rule,
+      teams: rule.selfReviewTeams ?? [],
+      users: rule.selfReviewUsers ?? [],
+    },
+    author,
+  );
+}
+
 /**
  * The first matched rule (closest-match order is preserved) for which the author
- * is an owner AND `self_review` is enabled — i.e. the rule that authorizes the
- * author to approve their own change. Undefined when none applies.
+ * may self-review — the rule that authorizes the author to approve their own
+ * change. Undefined when none applies.
  */
 function selfReviewRuleForAuthor(
   matchedRules: readonly AgenticOwnersPathRule[],
   author: ApprovalAuthor | undefined,
 ): AgenticOwnersPathRule | undefined {
-  return matchedRules.find((rule) => rule.selfReview && authorOwnsRule(rule, author));
+  return matchedRules.find((rule) => authorMaySelfReview(rule, author));
 }
 
 /**
@@ -180,7 +206,7 @@ export function authorSelfReviewCoversMatchedRules(
   );
   return (
     reviewCapableRules.length > 0 &&
-    reviewCapableRules.every((rule) => rule.selfReview && authorOwnsRule(rule, author))
+    reviewCapableRules.every((rule) => authorMaySelfReview(rule, author))
   );
 }
 
@@ -384,7 +410,7 @@ function baseApprovalVerdict(input: {
   // owner self_review on that same rule. Low-risk auto-approve never clears a
   // hard gate without self_review.
   const blockingHardGate = reviewRequiredRules.find(
-    (rule) => ruleIsHardGate(rule) && !(rule.selfReview && authorOwnsRule(rule, author)),
+    (rule) => ruleIsHardGate(rule) && !authorMaySelfReview(rule, author),
   );
   if (blockingHardGate !== undefined) {
     return requestVerdict("a matched policy requires human review");

package/templates/agentic-owners/bot/lib/owners/globalOverride.ts

@@ -0,0 +1,60 @@
+// Vendored from the Agentic Owners policy core; see README.md in this
+// directory. Precedence must stay identical to the source's.
+
+import type { AgenticOwnersPathRule } from "./types.js";
+
+/**
+ * Winners a root `global_overrides` entry must not change: owner-clearing
+ * carve-outs, hard gates, and notify rules.
+ */
+export function blocksGlobalOverride(rule: AgenticOwnersPathRule): boolean {
+  return (
+    rule.globalExclusion === true ||
+    rule.alwaysApprove ||
+    rule.mode === "hard" ||
+    rule.humanReviewRequired ||
+    rule.mode === "notify"
+  );
+}
+
+function unionOwners(lists: readonly (readonly string[])[]): string[] {
+  return [...new Set(lists.flat())];
+}
+
+function selfReviewOwners(rule: AgenticOwnersPathRule): {
+  readonly selfReviewTeams: readonly string[];
+  readonly selfReviewUsers: readonly string[];
+} {
+  return {
+    selfReviewTeams: rule.selfReviewTeams ?? rule.teams,
+    selfReviewUsers: rule.selfReviewUsers ?? rule.users,
+  };
+}
+
+/**
+ * Let override owners clear a file the winner owns by self-review. The
+ * winner's owners, reviewers, and lane are unchanged, so an author outside the
+ * override needs exactly the review they would without it. The winner's
+ * owners self-review only when the winner sets `self_review`. An override
+ * whose `self_review` a policy edit withheld grants nothing.
+ */
+export function mergeGlobalOverride(
+  winner: AgenticOwnersPathRule,
+  overrides: readonly AgenticOwnersPathRule[],
+): AgenticOwnersPathRule {
+  const granting = overrides.filter((rule) => rule.selfReview);
+  if (granting.length === 0) {
+    return winner;
+  }
+  const selfReviewers = winner.selfReview ? [winner, ...granting] : granting;
+  return {
+    ...winner,
+    selfReview: true,
+    selfReviewTeams: unionOwners(
+      selfReviewers.map((rule) => selfReviewOwners(rule).selfReviewTeams),
+    ),
+    selfReviewUsers: unionOwners(
+      selfReviewers.map((rule) => selfReviewOwners(rule).selfReviewUsers),
+    ),
+  };
+}