brainiac-github 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ad5b0842a1e9731e535de2a742f69efa1a243e956d34d3b2a3ec8f04813ec96
-  data.tar.gz: 4d01970f8f0ca48975fc66fb8197d0b94c16b0797eed937123af4c0639163168
+  metadata.gz: 15281b0cda1699aa7d7b959380a43bd992b9d7a1a8930eba464047b2ff959d05
+  data.tar.gz: a19b302521ae9d8711629e5b1785e3730a21fba35b01933fe7d1cbf78f77dd2c
 SHA512:
-  metadata.gz: 4d637b12f74f47258614b8114efa550baac3ef11073c3dd4320edd637335e761aa5ec50601d4042c119d4ac988cc6ebbe26f34a0905071a2b205725b9749d7a7
-  data.tar.gz: 279d75d005d2889eb5373b0161764cd82459ada1aab2e022c1449793a56bd0910592008f71a860909595e6da54bfe66de6349f8323a1510171feacb81d5815aa
+  metadata.gz: 0dce21620964ed25764860b9f697578579b9340f6e8dadbb8dc1751b8e41c70a99d3c0d3f1e4c7f9876ce2d4e415d06f369a38553cdeff368ac722f83acc8e5b
+  data.tar.gz: 4e38c8f2504dcd4f5bf0022a64debc513614d4073b846cfc6dab4ea3df249d9049a58a5c9518c1e40938877dd07ee54c7f0526097a97edd1482f6023114d9e30

data/README.md

@@ -24,71 +24,193 @@ Config lives at `~/.brainiac/github.json`:
 ```json
 {
   "webhook_secret": "your-github-webhook-secret",
-  "app": {
-    "id": "123456",
-    "private_key_path": "~/.brainiac/github-app-private-key.pem",
-    "installation_id": "78901234"
+  "allowed_owners": ["stowzilla", "ardavis"],
+  "apps": {
+    "brainiac": {
+      "id": "100000",
+      "private_key_path": "~/.brainiac/brainiac.pem",
+      "installations": {
+        "stowzilla": "11111111",
+        "ardavis": "22222222"
+      }
+    },
+    "galen": {
+      "id": "200000",
+      "private_key_path": "~/.brainiac/galen-brainiac.pem",
+      "installations": {
+        "stowzilla": "33333333",
+        "ardavis": "44444444"
+      }
+    }
   },
   "repos": {}
 }
 ```
 
+The `allowed_owners` array restricts which GitHub accounts/orgs can trigger your
+agents. Events from repos not owned by a listed account are rejected with a 403
+before any processing occurs. If omitted, all owners are accepted (filtered
+downstream by project matching instead).
+
 Generate a webhook secret:
 
 ```bash
 ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
 ```
 
-### GitHub App Setup (Recommended)
+### GitHub App Setup
+
+The plugin uses GitHub Apps for two purposes:
+
+1. **Inbound events** — a single "Brainiac" app receives webhook events from all repos
+2. **Outbound identity** — per-agent apps post comments/reactions with distinct avatars
+
+This mirrors how Discord works: one gateway delivers all messages, each bot responds
+with its own token and avatar.
+
+#### Architecture
+
+```
+brainiac (app)       → webhook ACTIVE, receives all events
+galen-brainiac (app) → webhook DISABLED, Galen's posting identity
+glados-brainiac (app)→ webhook DISABLED, GLaDOS's posting identity
+```
 
-Using a GitHub App makes PR comments and reactions appear as the app's bot user
-(e.g. "brainiac-bot") instead of your personal account. This gives each agent a
-distinct identity in PR conversations.
+The "brainiac" agent in the registry also uses the brainiac app as its posting
+identity — so the webhook-receiver app doubles as the brainiac agent's identity.
+
+#### Step 1: Create the Brainiac App (Webhook Receiver)
 
 1. Go to **Settings → Developer settings → GitHub Apps → New GitHub App**
 2. Set the following:
-   - **Name**: e.g. `brainiac-bot`
+   - **Name**: `brainiac` (or your preferred orchestrator name)
    - **Homepage URL**: your Brainiac instance URL
-   - **Webhook URL**: leave blank (webhook is handled by the plugin directly)
-   - **Permissions**:
-     - Pull requests: Read & Write
-     - Issues: Read & Write
-     - Contents: Read (for fetching PR diffs)
-   - **Events**: uncheck everything (events come via the repo webhook, not the app)
-3. Create the app and note the **App ID** from the app's settings page
-4. Generate a private key (`.pem` file) and save it to `~/.brainiac/github-app-private-key.pem`
-5. Install the app on your org/repos and note the **Installation ID** from the URL:
-   `https://github.com/settings/installations/INSTALLATION_ID`
-6. Add the credentials to your `github.json`:
-   ```json
-   {
-     "app": {
-       "id": "123456",
-       "private_key_path": "~/.brainiac/github-app-private-key.pem",
-       "installation_id": "78901234"
-     }
-   }
+   - **Webhook URL**: `https://your-ngrok.ngrok-free.app/github`
+   - **Webhook secret**: paste the `webhook_secret` from your `github.json`
+3. Under **"Where can this GitHub App be installed?"**, select **"Any account"**
+   (allows installation on both personal accounts and organizations)
+4. Set **Permissions** (under "Repository permissions"):
+   - **Contents**: Read-only
+   - **Issues**: Read & Write
+   - **Pull requests**: Read & Write
+5. **Subscribe to events**:
+   - Issue comment
+   - Issues
+   - Pull request
+   - Pull request review
+   - Workflow run
+6. Create the app and note the **App ID**
+7. Generate a private key (see [Private Key Details](#private-key-details) below)
+8. Upload an avatar for the app
+9. **Install the app** on each account/org where you have repos:
+   - Go to the app's settings → "Install App" tab
+   - Install on your personal account (e.g. `ardavis`) — note the Installation ID
+     from the URL: `https://github.com/settings/installations/INSTALLATION_ID`
+   - Install on your org (e.g. `stowzilla`) — note that Installation ID too
+
+#### Step 2: Create Agent Identity Apps (One Per Agent)
+
+For each agent that should have its own avatar on PR comments:
+
+1. Go to **Settings → Developer settings → GitHub Apps → New GitHub App**
+2. Set the following:
+   - **Name**: `galen-brainiac`, `glados-brainiac`, etc.
+   - **Homepage URL**: your Brainiac instance URL
+   - **Webhook**: uncheck **"Active"** (these apps don't receive events)
+3. Under **"Where can this GitHub App be installed?"**, select **"Any account"**
+4. Set **Permissions** (under "Repository permissions"):
+   - **Contents**: Read-only
+   - **Issues**: Read & Write
+   - **Pull requests**: Read & Write
+5. **Do NOT subscribe to any events** (webhook is disabled)
+6. Create the app and note the **App ID**
+7. Generate a private key
+8. Upload the agent's **avatar**
+9. **Install the app** on each account/org (same as the brainiac app)
+10. Repeat for each agent
+
+#### Step 3: Configure `github.json`
+
+```json
+{
+  "webhook_secret": "your-github-webhook-secret",
+  "allowed_owners": ["stowzilla", "ardavis"],
+  "apps": {
+    "brainiac": {
+      "id": "100000",
+      "private_key_path": "~/.brainiac/brainiac.pem",
+      "installations": {
+        "stowzilla": "11111111",
+        "ardavis": "22222222"
+      }
+    },
+    "galen": {
+      "id": "200000",
+      "private_key_path": "~/.brainiac/galen-brainiac.pem",
+      "installations": {
+        "stowzilla": "33333333",
+        "ardavis": "44444444"
+      }
+    },
+    "glados": {
+      "id": "300000",
+      "private_key_path": "~/.brainiac/glados-brainiac.pem",
+      "installations": {
+        "stowzilla": "55555555",
+        "ardavis": "66666666"
+      }
+    }
+  },
+  "repos": {}
+}
+```
+
+Each key in `apps` matches the agent's registry key (lowercase). The
+`installations` hash maps account/org names to their Installation IDs.
+
+#### Private Key Details
+
+The `.pem` file is generated by GitHub — you don't create it yourself. On your
+app's settings page (Settings → Developer settings → GitHub Apps → your app):
+
+1. Scroll to the **"Private keys"** section
+2. Click **"Generate a private key"**
+3. GitHub generates an RSA key pair, keeps the public half, and your browser
+   downloads the private half as a `.pem` file (named like
+   `your-app-name.2026-08-06.private-key.pem`)
+4. Move it to your brainiac config directory and lock down permissions:
+   ```bash
+   mv ~/Downloads/your-app-name.*.private-key.pem ~/.brainiac/galen-brainiac.pem
+   chmod 600 ~/.brainiac/galen-brainiac.pem
    ```
 
-If app credentials are not configured, the plugin falls back to using the `gh` CLI
-(which authenticates as your personal GitHub account).
+The plugin uses this key to sign JWTs for GitHub API authentication. Never
+commit `.pem` files to version control.
+
+#### Fallback
+
+If no app credentials are configured for an agent, the plugin falls back to
+using the `gh` CLI (which authenticates as your personal GitHub account).
 
 ### Environment Variables
 
-As an alternative to config file values, you can set:
+As an alternative to config file values, you can set (applies to single-app mode only):
 
 - `GITHUB_WEBHOOK_SECRET` — webhook signature secret
 - `GITHUB_APP_ID` — GitHub App ID
 - `GITHUB_APP_PRIVATE_KEY_PATH` — path to the `.pem` private key file
 - `GITHUB_APP_INSTALLATION_ID` — installation ID
 
+For per-agent apps, use the config file — env vars don't support multiple apps.
+
 ### GitHub Webhook Setup
 
-1. Go to your repo → Settings → Webhooks → Add webhook
-2. Payload URL: `https://your-ngrok.ngrok-free.app/github`
-3. Content type: `application/json`
-4. Secret: paste your `webhook_secret`
-5. Events: Pull requests, Pull request reviews, Issue comments, Issues, Workflow runs
+The webhook is configured on the Brainiac app itself (Step 1 above) — no
+per-repo webhook setup is needed. The app-level webhook automatically receives
+events from all repos where the app is installed.
+
+If you have legacy per-repo webhooks pointing to `/github`, remove them to
+avoid duplicate event deliveries.
 
 ## CLI
 

data/lib/brainiac/plugins/github/app_client.rb

@@ -16,19 +16,27 @@ module Brainiac
       # API calls are made as the App's bot user — so PR comments, reactions, etc.
       # appear with the App's identity rather than a personal user.
       #
-      # Falls back to `gh` CLI when app credentials are not configured.
+      # Supports per-agent apps: if "apps" hash in config has an entry for the agent,
+      # that agent's app credentials are used (separate avatar/identity per agent).
+      # Falls back to shared "app" config, then to `gh` CLI.
       module AppClient
         GITHUB_API = "https://api.github.com"
         TOKEN_EXPIRY_BUFFER = 60 # refresh token 60s before expiry
 
-        @token = nil
-        @token_expires_at = nil
+        # Per-agent token cache: { agent_key_or_nil => { token:, expires_at: } }
+        @tokens = {}
         @mutex = Mutex.new
 
         class << self
           # Returns true if GitHub App credentials are fully configured.
-          def configured?
-            !!(Config.app_id && Config.private_key_path && Config.installation_id)
+          # Checks per-agent first, then shared app config.
+          # Guards against empty-string values (common in template configs).
+          def configured?(agent_key = nil)
+            id = Config.app_id(agent_key)
+            key_path = Config.private_key_path(agent_key)
+            inst_id = Config.installation_id(agent_key)
+
+            !!(id && !id.empty? && key_path && inst_id && !inst_id.empty?)
           end
 
           # POST a comment on an issue or PR.
@@ -36,9 +44,10 @@ module Brainiac
           # @param repo [String] "owner/repo"
           # @param pr_number [Integer]
           # @param body [String] comment markdown
+          # @param agent_key [String, nil] agent key for per-agent app identity
           # @return [Hash] parsed response
-          def create_comment(repo, pr_number, body)
-            post("/repos/#{repo}/issues/#{pr_number}/comments", { body: body })
+          def create_comment(repo, pr_number, body, agent_key: nil)
+            post("/repos/#{repo}/issues/#{pr_number}/comments", { body: body }, agent_key: agent_key)
           end
 
           # POST a reaction on an issue comment.
@@ -46,9 +55,10 @@ module Brainiac
           # @param repo [String] "owner/repo"
           # @param comment_id [Integer]
           # @param reaction [String] e.g. "eyes", "+1", "rocket"
+          # @param agent_key [String, nil] agent key for per-agent app identity
           # @return [Hash] parsed response
-          def create_comment_reaction(repo, comment_id, reaction)
-            post("/repos/#{repo}/issues/comments/#{comment_id}/reactions", { content: reaction })
+          def create_comment_reaction(repo, comment_id, reaction, agent_key: nil)
+            post("/repos/#{repo}/issues/comments/#{comment_id}/reactions", { content: reaction }, agent_key: agent_key)
           end
 
           # POST a reaction on a PR review.
@@ -56,40 +66,51 @@ module Brainiac
           # @param repo [String] "owner/repo"
           # @param review_id [Integer]
           # @param reaction [String]
+          # @param agent_key [String, nil] agent key for per-agent app identity
           # @return [Hash] parsed response
-          def create_review_reaction(repo, review_id, reaction)
-            post("/repos/#{repo}/pulls/reviews/#{review_id}/reactions", { content: reaction })
+          def create_review_reaction(repo, review_id, reaction, agent_key: nil)
+            post("/repos/#{repo}/pulls/reviews/#{review_id}/reactions", { content: reaction }, agent_key: agent_key)
           end
 
           # GET request to GitHub API.
           #
           # @param path [String] API path (e.g. "/repos/owner/repo/pulls/1")
+          # @param agent_key [String, nil] agent key for per-agent app identity
           # @return [Hash] parsed response
-          def get(path)
-            request(:get, path)
+          def get(path, agent_key: nil)
+            request(:get, path, agent_key: agent_key)
           end
 
           # POST request to GitHub API.
           #
           # @param path [String] API path
           # @param body [Hash] request body
+          # @param agent_key [String, nil] agent key for per-agent app identity
           # @return [Hash] parsed response
-          def post(path, body)
-            request(:post, path, body)
+          def post(path, body, agent_key: nil)
+            request(:post, path, body, agent_key: agent_key)
           end
 
-          # Reset cached token (useful for testing or when credentials change).
+          # Reset cached tokens (useful for testing or when credentials change).
           def reset!
             @mutex.synchronize do
-              @token = nil
-              @token_expires_at = nil
+              @tokens = {}
             end
           end
 
+          # Public accessor for installation tokens (used to inject GH_TOKEN into agent env).
+          # Returns the raw token string, or nil on failure.
+          def installation_token_for(agent_key = nil, repo_owner: nil)
+            installation_token(agent_key, repo_owner: repo_owner)
+          rescue StandardError
+            nil
+          end
+
           private
 
-          def request(method, path, body = nil)
-            token = installation_token
+          def request(method, path, body = nil, agent_key: nil)
+            repo_owner = extract_repo_owner(path)
+            token = installation_token(agent_key, repo_owner: repo_owner)
             uri = URI("#{GITHUB_API}#{path}")
 
             http = Net::HTTP.new(uri.host, uri.port)
@@ -118,16 +139,22 @@ module Brainiac
             JSON.parse(response.body)
           end
 
+          # Extract the repo owner from an API path like "/repos/stowzilla/brainiac/pulls/1"
+          def extract_repo_owner(path)
+            match = path.match(%r{^/repos/([^/]+)/})
+            match&.[](1)
+          end
+
           # Generate a short-lived JWT signed with the App's private key.
           # Used to request an installation access token.
-          def generate_jwt
-            private_key = OpenSSL::PKey::RSA.new(File.read(Config.private_key_path))
+          def generate_jwt(agent_key = nil)
+            private_key = OpenSSL::PKey::RSA.new(File.read(Config.private_key_path(agent_key)))
             now = Time.now.to_i
 
             payload = {
               iat: now - 60, # issued at (60s clock drift allowance)
               exp: now + (10 * 60), # expires in 10 minutes (max allowed)
-              iss: Config.app_id
+              iss: Config.app_id(agent_key)
             }
 
             JWT.encode(payload, private_key, "RS256")
@@ -135,12 +162,19 @@ module Brainiac
 
           # Fetch or return a cached installation access token.
           # Tokens are valid for 1 hour; we refresh 60s early.
-          def installation_token
+          # Cache key includes agent_key and repo_owner for proper scoping.
+          def installation_token(agent_key = nil, repo_owner: nil)
+            inst_id = Config.installation_id(agent_key, repo_owner: repo_owner)
+            raise "No installation ID configured#{" for #{repo_owner}" if repo_owner}" unless inst_id
+
+            cache_key = "#{agent_key || "shared"}-#{inst_id}"
+
             @mutex.synchronize do
-              return @token if @token && @token_expires_at && Time.now.to_i < @token_expires_at
+              cached = @tokens[cache_key]
+              return cached[:token] if cached && Time.now.to_i < cached[:expires_at]
 
-              jwt = generate_jwt
-              uri = URI("#{GITHUB_API}/app/installations/#{Config.installation_id}/access_tokens")
+              jwt = generate_jwt(agent_key)
+              uri = URI("#{GITHUB_API}/app/installations/#{inst_id}/access_tokens")
 
               http = Net::HTTP.new(uri.host, uri.port)
               http.use_ssl = true
@@ -158,11 +192,11 @@ module Brainiac
               raise "Failed to get installation token: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
               data = JSON.parse(response.body)
-              @token = data["token"]
-              # Parse expiry, subtract buffer
-              expires_at = Time.parse(data["expires_at"]).to_i
-              @token_expires_at = expires_at - TOKEN_EXPIRY_BUFFER
-              @token
+              token = data["token"]
+              expires_at = Time.parse(data["expires_at"]).to_i - TOKEN_EXPIRY_BUFFER
+
+              @tokens[cache_key] = { token: token, expires_at: expires_at }
+              token
             end
           end
         end

data/lib/brainiac/plugins/github/config.rb

@@ -30,26 +30,83 @@ module Brainiac
             @config["webhook_secret"] || ENV.fetch("GITHUB_WEBHOOK_SECRET", nil)
           end
 
-          # GitHub App credentials — all three must be present for App auth to work.
+          # Per-agent app credentials from the "apps" hash.
+          # Falls back to the shared "app" config if no per-agent entry exists.
 
-          def app_id
-            @config.dig("app", "id")&.to_s || ENV.fetch("GITHUB_APP_ID", nil)
+          def app_id(agent_key = nil)
+            per_agent_value(agent_key, "id") ||
+              @config.dig("app", "id")&.to_s ||
+              ENV.fetch("GITHUB_APP_ID", nil)
           end
 
-          def private_key_path
-            path = @config.dig("app", "private_key_path") || ENV.fetch("GITHUB_APP_PRIVATE_KEY_PATH", nil)
+          def private_key_path(agent_key = nil)
+            path = per_agent_value(agent_key, "private_key_path") ||
+                   @config.dig("app", "private_key_path") ||
+                   ENV.fetch("GITHUB_APP_PRIVATE_KEY_PATH", nil)
             return nil unless path
 
             expanded = File.expand_path(path)
             File.exist?(expanded) ? expanded : nil
           end
 
-          def installation_id
-            @config.dig("app", "installation_id")&.to_s || ENV.fetch("GITHUB_APP_INSTALLATION_ID", nil)
+          def installation_id(agent_key = nil, repo_owner: nil)
+            # Check per-agent config first
+            if agent_key
+              normalized = agent_key.to_s.downcase
+              agent_conf = @config.dig("apps", normalized)
+              if agent_conf
+                # Per-agent may have multiple installations keyed by owner
+                if repo_owner && agent_conf["installations"]
+                  return agent_conf.dig("installations", repo_owner)&.to_s || agent_conf["installation_id"]&.to_s
+                end
+
+                # Flat installation_id
+                return agent_conf["installation_id"]&.to_s if agent_conf["installation_id"]
+
+                # No repo_owner specified but installations hash exists — return first available
+                # (used by configured? check where repo_owner isn't known yet)
+                return agent_conf["installations"].values.first&.to_s if agent_conf["installations"]&.any?
+              end
+            end
+
+            # Shared app config — check installations hash first, then flat installation_id
+            if repo_owner && @config.dig("app", "installations")
+              found = @config.dig("app", "installations", repo_owner)&.to_s
+              return found if found
+            end
+
+            @config.dig("app", "installation_id")&.to_s ||
+              ENV.fetch("GITHUB_APP_INSTALLATION_ID", nil)
+          end
+
+          # Returns the agent key that should be used for a given context.
+          # If per-agent apps are configured and the agent has an entry, returns that key.
+          # Otherwise returns nil (use shared app).
+          def agent_app_configured?(agent_key)
+            return false unless agent_key
+
+            !!@config.dig("apps", agent_key.to_s.downcase)
+          end
+
+          # Check if a repo owner is in the allowed_owners list.
+          # If allowed_owners is not configured (empty/missing), all owners are allowed.
+          def owner_allowed?(owner)
+            allowed = @config["allowed_owners"]
+            return true unless allowed.is_a?(Array) && !allowed.empty?
+
+            allowed.include?(owner)
           end
 
           private
 
+          def per_agent_value(agent_key, field)
+            return nil unless agent_key
+
+            # Agent names come in as display names ("Galen") but config keys are lowercase ("galen")
+            normalized = agent_key.to_s.downcase
+            @config.dig("apps", normalized, field)&.to_s
+          end
+
           def load_config
             return {} unless File.exist?(CONFIG_FILE)
 

data/lib/brainiac/plugins/github/handler.rb

@@ -134,6 +134,7 @@ module Brainiac
             comment_body = comment["body"] || ""
             comment_id = comment["id"]
             comment_user = comment.dig("user", "login")
+            comment_user_type = comment.dig("user", "type")
             repo_name = payload.dig("repository", "full_name")
 
             unless issue["pull_request"]
@@ -149,33 +150,51 @@ module Brainiac
 
             project_key, project_config = project_result
             pr_number = issue["number"]
+            agent_name = agent_name_for(project_config)
 
-            if AppClient.configured?
-              pr_response = AppClient.get("/repos/#{repo_name}/pulls/#{pr_number}")
-              branch = pr_response.dig("head", "ref")
-            else
-              pr_data = run_cmd("gh", "api", "/repos/#{repo_name}/pulls/#{pr_number}", "--jq", "{branch: .head.ref}",
-                                chdir: project_config["repo_path"])
-              branch = JSON.parse(pr_data)["branch"]
+            # Mention detection: if the comment mentions a specific agent, dispatch
+            # that agent instead of the project's default. This enables cross-agent
+            # reviews on PRs.
+            #
+            # Supported syntax (to avoid tagging real GitHub users with @):
+            #   "Threepio, review this"   — name + comma at the start
+            #   "/ask Threepio review"    — /ask Name
+            #   "/Threepio review this"   — /Name
+            #   "@Threepio review this"   — @Name (legacy, works but tags real users)
+            mentioned = detect_github_mention(comment_body)
+            if mentioned && mentioned.downcase != agent_name.downcase && local_agent_names.include?(mentioned)
+              LOG.info "[GitHub] Mention detected: #{mentioned} in PR comment (default agent: #{agent_name})"
+              agent_name = mentioned
             end
 
+            # Ignore comments from this project's own bot to prevent self-triggering.
+            # Cross-agent bot comments (e.g. GLaDOS commenting on Galen's PR) are still processed.
+            if comment_user_type == "Bot" && own_bot_comment?(comment_user, agent_name)
+              LOG.info "Ignoring self-triggered bot comment from #{comment_user} (agent: #{agent_name})"
+              return [200, { status: "ignored", reason: "self-triggered bot comment" }.to_json]
+            end
+
+            branch = fetch_pr_branch(repo_name, pr_number, agent_name, project_config)
             result = find_work_item_by_branch(branch)
 
-            if result
+            # If a work item exists and has an assigned agent, use that agent
+            # instead of the project default. This ensures comments on a PR
+            # route to whoever is actually working it (e.g. GLaDOS opened the PR,
+            # so GLaDOS should handle follow-up comments — not the project's default agent).
+            # Explicit mentions still take priority (already resolved above).
+            if result && !mentioned
               _, card_info = result
-              card_number = extract_card_number(card_info)
-              worktree = card_info["worktree"]
-
-              unless worktree && File.directory?(worktree)
-                LOG.info "No active worktree for PR ##{pr_number}, ignoring comment"
-                return [200, { status: "ignored", reason: "no active worktree" }.to_json]
+              work_item_agent = card_info["agent"]
+              if work_item_agent && work_item_agent.downcase != agent_name.downcase && local_agent_names.include?(work_item_agent)
+                LOG.info "[GitHub] Work item agent override: #{work_item_agent} (project default: #{agent_name})"
+                agent_name = work_item_agent
               end
-
-            else
-              card_number = nil
-              worktree = project_config["repo_path"]
             end
-            card_key = "pr-comment-#{repo_name.tr("/", "-")}-#{pr_number}"
+
+            card_number, worktree = resolve_comment_worktree(result, mentioned, agent_name, pr_number, project_config)
+            return worktree if worktree.is_a?(Array)
+
+            card_key = "pr-comment-#{repo_name.tr("/", "-")}-#{pr_number}-#{agent_name.downcase}"
 
             if session_active?(card_key)
               LOG.info "Skipping PR comment on #{card_key} — agent session already active"
@@ -185,7 +204,7 @@ module Brainiac
             card_context = card_number ? " for card ##{card_number}" : ""
             LOG.info "PR comment from #{comment_user} on PR ##{pr_number}#{card_context} (project: #{project_key})"
             dispatch_pr_comment(card_number, card_key, pr_number, comment_id, comment_user, comment_body,
-                                repo_name, worktree, project_key, project_config)
+                                repo_name, worktree, project_key, project_config, agent_name: agent_name)
 
             [200, { status: "processed", card: card_number, pr: pr_number, comment_id: comment_id, project: project_key }.to_json]
           rescue StandardError => e
@@ -248,12 +267,128 @@ module Brainiac
             nil
           end
 
+          # Generate a GH_TOKEN env var for the agent process so `gh` CLI
+          # authenticates as the app bot instead of the user's personal account.
+          # Falls back to the shared "brainiac" app if the agent's own app isn't configured.
+          # Returns empty hash if no app credentials are available at all.
+          def github_agent_env(agent_name, repo_name)
+            # Try agent's own app first, fall back to shared "brainiac" app
+            effective_agent = if AppClient.configured?(agent_name)
+                                agent_name
+                              elsif AppClient.configured?("brainiac")
+                                LOG.info "[GitHub] Agent #{agent_name} has no app configured, falling back to shared brainiac app"
+                                "brainiac"
+                              end
+            return {} unless effective_agent
+
+            repo_owner = repo_name.split("/").first
+            token = AppClient.installation_token_for(effective_agent, repo_owner: repo_owner)
+            return {} unless token
+
+            { "GH_TOKEN" => token }
+          rescue StandardError => e
+            LOG.warn "[GitHub] Could not generate agent token: #{e.message}"
+            {}
+          end
+
           # Extract the card number from a work item info hash, supporting both
           # the old flat format ("number") and new source-based format ("sources.fizzy.card_number").
           def extract_card_number(card_info)
             card_info["number"] || card_info.dig("sources", "fizzy", "card_number")
           end
 
+          # Resolve the agent name from a work item, falling back to the project default.
+          # Work items track which agent is assigned (e.g. GLaDOS opened the PR), so
+          # comments/reviews should route to that agent rather than the project default.
+          def resolve_work_item_agent(card_info, project_config)
+            work_item_agent = card_info["agent"] if card_info
+            if work_item_agent && local_agent_names.include?(work_item_agent)
+              work_item_agent
+            else
+              agent_name_for(project_config)
+            end
+          end
+
+          # Fetch the head branch name of a PR using the GitHub App or `gh` CLI.
+          def fetch_pr_branch(repo_name, pr_number, agent_name, project_config)
+            if AppClient.configured?(agent_name)
+              pr_response = AppClient.get("/repos/#{repo_name}/pulls/#{pr_number}", agent_key: agent_name)
+              pr_response.dig("head", "ref")
+            else
+              pr_data = run_cmd("gh", "api", "/repos/#{repo_name}/pulls/#{pr_number}", "--jq", "{branch: .head.ref}",
+                                chdir: project_config["repo_path"])
+              JSON.parse(pr_data)["branch"]
+            end
+          end
+
+          # Resolve the card number and worktree for a PR comment.
+          # Returns [card_number, worktree_path] on success, or a Rack response array
+          # (to be returned early) when the comment should be ignored.
+          def resolve_comment_worktree(result, mentioned, agent_name, pr_number, project_config)
+            return [nil, project_config["repo_path"]] unless result
+
+            _, card_info = result
+            card_number = extract_card_number(card_info)
+            worktree = card_info["worktree"]
+
+            is_mention = mentioned && mentioned.downcase == agent_name.downcase
+            if is_mention
+              worktree = project_config["repo_path"] unless worktree && File.directory?(worktree)
+            else
+              unless worktree && File.directory?(worktree)
+                LOG.info "No active worktree for PR ##{pr_number}, ignoring comment"
+                return [200, { status: "ignored", reason: "no active worktree" }.to_json]
+              end
+            end
+
+            [card_number, worktree]
+          end
+
+          # Detect an agent mention in a GitHub PR comment using syntax that
+          # avoids tagging real GitHub users.
+          #
+          # Supported patterns (case-insensitive):
+          #   "Threepio, review this"        — agent name + comma at the start of text
+          #   "/ask Threepio review"         — /ask followed by agent name
+          #   "/Threepio review this"        — slash followed by agent name
+          #   "@threepio-brainiac review"    — @name-brainiac (matches bot username pattern)
+          #
+          # Returns the display name of the matched agent, or nil.
+          def detect_github_mention(text)
+            return nil if text.nil? || text.strip.empty?
+
+            downcased = text.strip.downcase
+            agent_names = all_agent_names
+
+            agent_names.each do |name|
+              name_lower = name.downcase
+
+              # Pattern: "Name, ..." at the start (vocative)
+              return name if downcased.match?(/\A#{Regexp.escape(name_lower)}\s*,/)
+
+              # Pattern: "/ask Name ..."
+              return name if downcased.match?(%r{\A/ask\s+#{Regexp.escape(name_lower)}\b})
+
+              # Pattern: "/Name ..."
+              return name if downcased.match?(%r{\A/#{Regexp.escape(name_lower)}\b})
+
+              # Pattern: "@Name-brainiac ..." (matches the bot account naming convention)
+              return name if downcased.match?(/@#{Regexp.escape(name_lower)}-brainiac\b/)
+            end
+
+            nil
+          end
+
+          # Check if a bot comment is from the same agent that would handle this PR.
+          # e.g. "galen-brainiac[bot]" is a self-trigger for agent "Galen",
+          # but "glados-brainiac[bot]" is a cross-agent request and should be processed.
+          def own_bot_comment?(bot_login, agent_name)
+            # Bot logins are like "galen-brainiac[bot]" — check if it starts with the agent name
+            normalized_login = bot_login.to_s.downcase.delete_suffix("[bot]")
+            normalized_agent = agent_name.to_s.downcase
+            normalized_login.start_with?(normalized_agent)
+          end
+
           # Extract PRs array from a work item, supporting both old flat format and new source-based format.
           def extract_prs(card_info)
             card_info.dig("sources", "github", "prs") || card_info["prs"] || []
@@ -308,10 +443,12 @@ module Brainiac
           end
 
           def dispatch_pr_comment(card_number, card_key, pr_number, comment_id, comment_user, comment_body,
-                                  repo_name, worktree, project_key, project_config)
+                                  repo_name, worktree, project_key, project_config, agent_name: nil)
+            agent_name ||= agent_name_for(project_config)
+
             Thread.new do
-              if AppClient.configured?
-                AppClient.create_comment_reaction(repo_name, comment_id, "eyes")
+              if AppClient.configured?(agent_name)
+                AppClient.create_comment_reaction(repo_name, comment_id, "eyes", agent_key: agent_name)
               else
                 run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/issues/comments/#{comment_id}/reactions",
                         "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: worktree)
@@ -320,7 +457,6 @@ module Brainiac
               LOG.warn "Could not add reaction to comment: #{e.message}"
             end
 
-            agent_name = agent_name_for(project_config)
             prompt = render_prompt(Prompts::PR_COMMENT,
                                    { "CARD_NUMBER" => card_number || "PR-#{pr_number}",
                                      "CARD_ID" => card_number || "PR-#{pr_number}",
@@ -330,15 +466,18 @@ module Brainiac
                                                                       project_key: project_key, comment_body: comment_body),
                                    agent_name: agent_name, channel: :github)
 
-            intent_ctx = fetch_pr_intent_context(pr_number, repo_name)
-            pid, log_file = run_agent(prompt, project_config: project_config, chdir: worktree,
-                                              log_name: "pr-comment-#{pr_number}",
-                                              model: detect_model(project_config, text: comment_body),
-                                              effort: detect_effort(project_config, text: comment_body),
-                                              agent_name: agent_name, source: :github,
-                                              source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: worktree },
-                                              message: comment_body, channel: "GitHub PR comment",
-                                              context: intent_ctx)
+            intent_ctx = fetch_pr_intent_context(pr_number, repo_name, agent_name)
+            agent_env = github_agent_env(agent_name, repo_name)
+            run_agent_opts = { project_config: project_config, chdir: worktree,
+                               log_name: "pr-comment-#{pr_number}",
+                               model: detect_model(project_config, text: comment_body),
+                               effort: detect_effort(project_config, text: comment_body),
+                               agent_name: agent_name, source: :github,
+                               source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: worktree },
+                               message: comment_body, channel: "GitHub PR comment",
+                               context: intent_ctx }
+            run_agent_opts[:env] = agent_env if method(:run_agent).parameters.flatten.include?(:env)
+            pid, log_file = run_agent(prompt, **run_agent_opts)
             return unless pid
 
             register_session(card_key, pid, log_file: log_file, agent_name: agent_name)
@@ -347,24 +486,25 @@ module Brainiac
           def dispatch_pr_review(card_number, card_key, card_info, pr_number, review, reviewer,
                                  repo_name, project_key, project_config, repo_path)
             review_id = review["id"]
+            agent_name = resolve_work_item_agent(card_info, project_config)
+
             Thread.new do
-              if AppClient.configured?
-                AppClient.create_review_reaction(repo_name, review_id, "eyes")
+              if AppClient.configured?(agent_name)
+                AppClient.create_review_reaction(repo_name, review_id, "eyes", agent_key: agent_name)
               else
                 run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/pulls/reviews/#{review_id}/reactions",
                         "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: repo_path)
               end
 
-              react_to_review_comments(review_id, pr_number, repo_name, repo_path)
+              react_to_review_comments(review_id, pr_number, repo_name, repo_path, agent_name)
             rescue StandardError => e
               LOG.warn "Could not add reaction to review: #{e.message}"
             end
 
-            agent_name = agent_name_for(project_config)
             Brainiac.emit(:pr_review_received, card_number: card_number, reviewer: reviewer,
                                                agent_name: agent_name, project_config: project_config, repo_path: repo_path)
 
-            review_context = build_review_context(reviewer, review, pr_number, repo_name)
+            review_context = build_review_context(reviewer, review, pr_number, repo_name, agent_name)
             worktree = card_info["worktree"]
             work_dir = worktree && File.directory?(worktree) ? worktree : repo_path
 
@@ -377,23 +517,26 @@ module Brainiac
                                                                       project_key: project_key),
                                    agent_name: agent_name, channel: :github)
 
-            pid, log_file = run_agent(prompt, project_config: project_config, chdir: work_dir,
-                                              log_name: "review-#{card_number || "pr-#{pr_number}"}",
-                                              agent_name: agent_name,
-                                              source: :github,
-                                              source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: work_dir },
-                                              message: review["body"], channel: "GitHub PR review",
-                                              context: fetch_pr_intent_context(pr_number, repo_name))
+            agent_env = github_agent_env(agent_name, repo_name)
+            run_agent_opts = { project_config: project_config, chdir: work_dir,
+                               log_name: "review-#{card_number || "pr-#{pr_number}"}",
+                               agent_name: agent_name,
+                               source: :github,
+                               source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: work_dir },
+                               message: review["body"], channel: "GitHub PR review",
+                               context: fetch_pr_intent_context(pr_number, repo_name, agent_name) }
+            run_agent_opts[:env] = agent_env if method(:run_agent).parameters.flatten.include?(:env)
+            pid, log_file = run_agent(prompt, **run_agent_opts)
             return unless pid
 
             register_session(card_key, pid, log_file: log_file, agent_name: agent_name)
           end
 
-          def build_review_context(reviewer, review, pr_number, repo_name)
+          def build_review_context(reviewer, review, pr_number, repo_name, agent_key = nil)
             context = "GitHub PR Review from @#{reviewer}:\n\n"
             context += "Review body:\n#{review["body"]}\n\n" if review["body"] && !review["body"].empty?
 
-            review_comments = fetch_pr_review_comments(pr_number, repo_name)
+            review_comments = fetch_pr_review_comments(pr_number, repo_name, agent_key)
             if review_comments.any?
               context += "Line-specific comments:\n"
               review_comments.each do |comment|
@@ -403,9 +546,9 @@ module Brainiac
             context
           end
 
-          def fetch_pr_review_comments(pr_number, repo)
-            if AppClient.configured?
-              response = AppClient.get("/repos/#{repo}/pulls/#{pr_number}/comments")
+          def fetch_pr_review_comments(pr_number, repo, agent_key = nil)
+            if AppClient.configured?(agent_key)
+              response = AppClient.get("/repos/#{repo}/pulls/#{pr_number}/comments", agent_key: agent_key)
               # Response is an array of comment objects
               response.map { |c| { "path" => c["path"], "line" => c["line"], "body" => c["body"], "user" => c.dig("user", "login") } }
             else
@@ -421,9 +564,9 @@ module Brainiac
 
           # React with 👀 to each individual comment in a review submission.
           # This makes reactions visible on line-level file comments, not just the review wrapper.
-          def react_to_review_comments(review_id, pr_number, repo_name, repo_path)
-            if AppClient.configured?
-              comments = AppClient.get("/repos/#{repo_name}/pulls/#{pr_number}/reviews/#{review_id}/comments")
+          def react_to_review_comments(review_id, pr_number, repo_name, repo_path, agent_key = nil)
+            if AppClient.configured?(agent_key)
+              comments = AppClient.get("/repos/#{repo_name}/pulls/#{pr_number}/reviews/#{review_id}/comments", agent_key: agent_key)
               comment_ids = comments.map { |c| c["id"] }
             else
               output = run_cmd("gh", "api", "/repos/#{repo_name}/pulls/#{pr_number}/reviews/#{review_id}/comments",
@@ -432,8 +575,8 @@ module Brainiac
             end
 
             comment_ids.each do |comment_id|
-              if AppClient.configured?
-                AppClient.create_comment_reaction(repo_name, comment_id, "eyes")
+              if AppClient.configured?(agent_key)
+                AppClient.create_comment_reaction(repo_name, comment_id, "eyes", agent_key: agent_key)
               else
                 run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/pulls/comments/#{comment_id}/reactions",
                         "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: repo_path)
@@ -445,9 +588,9 @@ module Brainiac
 
           # Lightweight recent PR comment context for intent classification.
           # Returns "author: message" format (last 5 issue comments on the PR).
-          def fetch_pr_intent_context(pr_number, repo_name)
-            if AppClient.configured?
-              comments = AppClient.get("/repos/#{repo_name}/issues/#{pr_number}/comments")
+          def fetch_pr_intent_context(pr_number, repo_name, agent_key = nil)
+            if AppClient.configured?(agent_key)
+              comments = AppClient.get("/repos/#{repo_name}/issues/#{pr_number}/comments", agent_key: agent_key)
               entries = comments.last(5).map { |c| "#{c.dig("user", "login")}: #{c["body"]&.slice(0, 200)}" }
               return nil if entries.empty?
 

data/lib/brainiac/plugins/github/version.rb

@@ -3,7 +3,7 @@
 module Brainiac
   module Plugins
     module Github
-      VERSION = "0.1.0"
+      VERSION = "0.2.1"
     end
   end
 end

data/lib/brainiac/plugins/github.rb

@@ -64,13 +64,14 @@ module Brainiac
 
             work_dir = source_context[:work_dir] || Dir.pwd
             agent_display = ctx[:agent_name] || "Agent"
+            agent_key = ctx[:agent_key]
             snippet = ctx[:snippet]
             snippet_block = snippet ? "\n```\n#{snippet[-1500..]}\n```" : ""
             comment_body = "💥 **#{agent_display} crashed** (exit code #{ctx[:exit_status]})\n\nLog: `#{ctx[:log_file]}`#{snippet_block}"
 
             begin
-              if AppClient.configured?
-                AppClient.create_comment(repo_name, pr_number, comment_body)
+              if AppClient.configured?(agent_key)
+                AppClient.create_comment(repo_name, pr_number, comment_body, agent_key: agent_key)
               else
                 run_cmd("gh", "pr", "comment", pr_number.to_s, "--repo", repo_name, "--body", comment_body, chdir: work_dir)
               end
@@ -89,11 +90,23 @@ module Brainiac
             request.body.rewind
             payload_body = request.body.read
 
+            # Dedup: GitHub sends X-GitHub-Delivery as a unique ID per webhook delivery.
+            # Drop duplicates (can occur due to threading or retries).
+            delivery_id = request.env["HTTP_X_GITHUB_DELIVERY"]
+            if delivery_id && Brainiac::Plugins::Github.already_delivered?(delivery_id)
+              halt 200, { status: "ignored", reason: "duplicate delivery" }.to_json
+            end
+
             Brainiac::Plugins::Github.verify_signature!(request, payload_body)
 
             payload = JSON.parse(payload_body)
             event = request.env["HTTP_X_GITHUB_EVENT"]
 
+            repo_owner = payload.dig("repository", "owner", "login")
+            if repo_owner && !Brainiac::Plugins::Github::Config.owner_allowed?(repo_owner)
+              halt 403, { error: "Repository owner not in allowed_owners", owner: repo_owner }.to_json
+            end
+
             reload_projects!
             reload_agent_registry!
             Brainiac::Plugins::Github::Config.reload!
@@ -169,6 +182,21 @@ module Brainiac
         computed = "sha256=#{OpenSSL::HMAC.hexdigest("sha256", secret, payload_body)}"
         halt 403, { error: "Invalid GitHub signature" }.to_json unless Rack::Utils.secure_compare(signature, computed)
       end
+
+      # Track recent delivery IDs to prevent duplicate processing.
+      # Thread-safe via Mutex. Keeps last 100 IDs.
+      @recent_deliveries = []
+      @delivery_mutex = Mutex.new
+
+      def self.already_delivered?(delivery_id)
+        @delivery_mutex.synchronize do
+          return true if @recent_deliveries.include?(delivery_id)
+
+          @recent_deliveries << delivery_id
+          @recent_deliveries.shift if @recent_deliveries.size > 100
+          false
+        end
+      end
     end
   end
 end

data/templates/github.json.example

@@ -1,5 +1,7 @@
 {
-  "webhook_secret": "your-github-webhook-secret",
+  "webhook_secret": "",
+  "allowed_owners": [],
+  "apps": {},
   "app": {
     "id": "",
     "private_key_path": "~/.brainiac/github-app-private-key.pem",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac-github
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Andy Davis