feat: honor agent labels in auto-pilot

.github/workflows/agents-auto-pilot.yml

@@ -1708,15 +1708,39 @@ jobs:
             const stepCount = parseInt(process.env.STEP_COUNT || '0') + 1;
 
             let agentKey = 'codex';
+            let issueLabels = [];
             try {
-              const { loadAgentRegistry } = require('./.github/scripts/agent_registry.js');
+              const { data: issue } = await withRetry((client) =>
+                client.rest.issues.get({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issueNumber
+                })
+              );
+              issueLabels = issue.labels || [];
+            } catch (fetchError) {
+              core.warning(`Failed to load issue labels before capability check: ${fetchError?.message || fetchError}`);
+            }
+            try {
+              const { loadAgentRegistry, resolveAgentFromLabels } = require('./.github/scripts/agent_registry.js');
               const registry = loadAgentRegistry();
-              const defaultAgent = registry.default_agent || agentKey;
-              agentKey = String(defaultAgent).trim().toLowerCase() || agentKey;
-              } catch (error) {
-                const prefix = `Failed to load agent registry; defaulting to ${agentKey}:`;
-                core.warning(`${prefix} ${error.message}`);
+              const defaultAgent = String(registry.default_agent || agentKey).trim().toLowerCase() || agentKey;
+              if (issueLabels.length) {
+                try {
+                  agentKey =
+                    resolveAgentFromLabels(issueLabels, { registryPath: './.github/agents/registry.yml' }) ||
+                    defaultAgent;
+                } catch (resolveError) {
+                  core.warning(`Failed to resolve agent label; defaulting to ${defaultAgent}: ${resolveError?.message || resolveError}`);
+                  agentKey = defaultAgent;
+                }
+              } else {
+                agentKey = defaultAgent;
               }
+            } catch (error) {
+              const prefix = `Failed to load agent registry; defaulting to ${agentKey}:`;
+              core.warning(`${prefix} ${error.message}`);
+            }
 
             await withRetry((client) => client.rest.issues.createComment({
               owner: context.repo.owner,
@@ -1969,13 +1993,37 @@ jobs:
             const issueTitle = process.env.ISSUE_TITLE || `Issue #${issueNumber}`;
             const stepCount = parseInt(process.env.STEP_COUNT || '0') + 1;
             let agentKey = 'codex';
+            let issueLabels = [];
             let branchPrefix = 'codex/issue-';
+            try {
+              const { data: issue } = await withRetry((client) =>
+                client.rest.issues.get({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issueNumber
+                })
+              );
+              issueLabels = issue.labels || [];
+            } catch (fetchError) {
+              core.warning(`Failed to load issue labels before create-pr: ${fetchError?.message || fetchError}`);
+            }
             try {
               const registryLib = require('./.github/scripts/agent_registry.js');
-              const { loadAgentRegistry, getAgentConfig } = registryLib;
+              const { loadAgentRegistry, getAgentConfig, resolveAgentFromLabels } = registryLib;
               const registry = loadAgentRegistry();
-              const defaultAgent = registry.default_agent || agentKey;
-              agentKey = String(defaultAgent).trim().toLowerCase() || agentKey;
+              const defaultAgent = String(registry.default_agent || agentKey).trim().toLowerCase() || agentKey;
+              if (issueLabels.length) {
+                try {
+                  agentKey =
+                    resolveAgentFromLabels(issueLabels, { registryPath: './.github/agents/registry.yml' }) ||
+                    defaultAgent;
+                } catch (resolveError) {
+                  core.warning(`Failed to resolve agent label; defaulting to ${defaultAgent}: ${resolveError?.message || resolveError}`);
+                  agentKey = defaultAgent;
+                }
+              } else {
+                agentKey = defaultAgent;
+              }
               const cfg = getAgentConfig(agentKey);
               branchPrefix = String(cfg.branch_prefix || branchPrefix);
             } catch (error) {

docs/WORKFLOW_GUIDE.md

@@ -97,7 +97,7 @@ _Inline Gate helper_
 - **`agents-72-codex-belt-worker.yml`** — Repository-dispatch consumer that re-validates labels, ensures the branch diverges from the base (empty commit when needed), and opens or refreshes the Codex automation PR with labels, assignees, and activation comment. Like the dispatcher it prefers App tokens, falls back to PAT/`GITHUB_TOKEN`, honours per-agent concurrency, and exposes a dry-run guard for diagnostics.
 - **`agents-73-codex-belt-conveyor.yml`** — Gate follower that squash-merges successful belt PRs, deletes the branch, closes the originating issue, posts audit breadcrumbs, and re-dispatches the dispatcher so the queue keeps moving. It reuses the shared API client for token load balancing, requires Gate success before merging, blocks bootstrap-only placeholders, and mirrors the same dry-run + concurrency protections as the dispatcher/worker.
 - **`agents-auto-label.yml`** — Issue/PR label suggester that feeds LangChain embeddings through the shared API client, applies labels with the default token, and posts suggestion comments when confidence drops below auto-apply thresholds. Removing the redundant App mint keeps the workflow lightweight on every issue event.
-- **`agents-auto-pilot.yml`** — Full issue-to-PR automation pipeline (format → optimize → apply → capability check → PR creation → keepalive → verify). The workflow stayed in service as-is; documentation now clarifies that it orchestrates the reusable agents stack and hands tasks to keepalive without additional per-job token churn.
+- **`agents-auto-pilot.yml`** — Full issue-to-PR automation pipeline (format → optimize → apply → capability check → PR creation → keepalive → verify). Apply `agents:auto-pilot` plus an optional `agent:<name>` label (for example `agent:claude`) to control which runner executes the PR work; if no explicit `agent:*` label exists, auto-pilot falls back to the registry default, adds that `agent:` label for you, and hands tasks to keepalive without extra per-job token churn.
 - **`agents-autofix-dispatcher.yml`** — Triggered when Gate posts `autofix_gate_failure`. It still needs a GitHub App token to dispatch `agents-autofix-loop.yml`, but otherwise the job simply forwards the failing run ID/PR/head SHA so the loop can attempt repairs.
 - **`agents-autofix-loop.yml`** — Handles larger fix-ups (pyproject sync, scripted rewrites, merge conflict handling) after the dispatcher fires. It respects PAT/App availability, retries with the shared API client, and labels PRs (`autofix:conflict`, `needs-human`) when automation cannot complete the repair.
 - **`agents-autofix-rebase.yml`** — Rebase helper kicked off from Gate when `mergeable_state` is `dirty`/`behind`. It merges the base branch into same-repo PRs with the App token, tagging the PR with `autofix:conflict` plus a comment whenever a manual rebase is still required.
@@ -112,7 +112,7 @@ _Inline Gate helper_
 - **`agents-pr-meta-v4.yml`** — PR metadata/keepalive front door: listens to issue comments, PR updates, and Gate completions to detect `@agent` activations, enforce gate/run-cap rules, dispatch the orchestrator, and write dispatch summaries. Still needs a GitHub App/PAT token when it re-dispatches keepalive, so the workflow remains in service until the consolidated orchestration stack replaces it.
 - **`agents-verifier.yml`** — Label-driven verification runner. When a merged PR gets `verify:*` (or when dispatched manually), it routes the request through the reusable verifier workflow to run checkbox/evaluate/compare modes, posts the structured summary, and opens follow-up issues on failures. It now mints a GitHub App token before checking out the caller repo/Workflows scripts so cross-repo verification works under the service account while still falling back to the installation token when App credentials are missing.
 - **`agents-verify-to-issue-v2.yml`** — Converts verification feedback into an agent-ready follow-up issue whenever `verify:create-issue` is applied to a merged PR. It gathers the verification comments, original issue context, and PR metadata, runs LangChain templates, and opens a structured issue using the appropriate PAT/App token so ownership stays consistent.
-- **`agents-verify-to-new-pr.yml`** — Handles the `verify:create-new-pr` label end-to-end: collects verification comments, reconstructs the original issue context, creates a follow-up issue, and now dispatches `agents-auto-pilot.yml` (optimize step) inline so automation continues without a separate bridge workflow.
+- **`agents-verify-to-new-pr.yml`** — Handles the `verify:create-new-pr` label end-to-end: collects verification comments, reconstructs the original issue context, creates a follow-up issue (carrying over the `agent:*` label from the merged PR or defaulting via the registry), and now dispatches `agents-auto-pilot.yml` (optimize step) inline so automation continues without a separate bridge workflow.
 - **`agents-moderate-connector.yml`** — Moderates connector-style PR comments. Uses allow/deny lists plus heuristics (checklist/commit/code indicators and known noise phrases) to delete “I can’t run Codex here” spam while preserving legitimate updates. Skips moderation when `agents:debug` is on the PR so humans can inspect noisy runs. Relies on the shared API client; no workflow changes were required.
 - **`agents-weekly-metrics.yml`** — Weekly cron that aggregates artifacts from keepalive, autofix, verifier, and auto-pilot runs, generates a Markdown summary, uploads it, and posts/updates the tracking issue. Now relies entirely on the shared API client (installation token) for artifact downloads and issue updates—no bespoke App token.
 

docs/keepalive/Agents.md

@@ -66,6 +66,7 @@ Auto-pilot pipeline:
 1. **Task Focus**: Agents must work on PR tasks, not unrelated improvements. Tasks are explicitly injected via the task appendix.
 
 2. **Agent Agnostic**: The keepalive prompt is agent-agnostic. Routing is determined by the `agent:*` label, not hardcoded agent names.
+   - Apply `agents:auto-pilot` together with an explicit `agent:codex`, `agent:claude`, etc. label when you want to pin the runner. If no `agent:*` label exists, auto-pilot uses the registry default and adds the matching label so keepalive, autofix, and verifier flows all stay aligned.
 
 3. **No `@codex` in Prompts**: Do not use `@codex` or other agent mentions in automated prompts—this can trigger the UI version of agents. Let the routing handle which agent runs.