@sentry/junior-github 0.102.2 → 0.103.0

package/SETUP.md

@@ -64,7 +64,7 @@ vercel env update GITHUB_APP_PRIVATE_KEY production --sensitive < ./github-app-p
 
 Repeat for `preview` and `development` as needed. After env changes, redeploy so the new deployment picks up updated values.
 
-### Optional permission overrides
+### Optional permission declaration
 
 By default, `installation-read` grants read the app installation's current permission envelope once per process and scopes read-capable permissions down to `read` when requesting a token. To declare the GitHub App permission envelope in the plugin and avoid that installation lookup, pass `appPermissions` when registering the plugin:
 
@@ -81,11 +81,11 @@ githubPlugin({
 });
 ```
 
-Junior records these permissions as plugin capabilities. The configured values are the maximum GitHub App envelope Junior may need for writes. Installation-read token requests remain read-only by requesting read-capable configured permissions at `read` level and omitting GitHub permission fields that have no `read` value. GitHub remains the source of truth for whether a permission name or level exists.
+Junior records these permissions as plugin capabilities. Installation-read token requests remain read-only by requesting read-capable configured permissions at `read` level and omitting GitHub permission fields that have no `read` value. Installation-write token requests intentionally omit the `permissions` field, so GitHub applies the complete permission envelope approved on the App installation. GitHub remains the source of truth for whether a permission name or level exists.
 
 GitHub App user-to-server tokens do not use OAuth scopes as their permission model. Their effective access is limited by the GitHub App's installed permissions, the app installation's repository access, and the requesting user's own GitHub access. Repository-scoped installation tokens instead use the App permission envelope and installation repository access without borrowing the requesting user's authority. GitHub returns an empty `scope` value for user-to-server tokens, so Junior cannot verify granted scopes from the token response.
 
-If you pass `additionalUserScopes`, Junior includes those values in the authorization URL and records the requested scope string as a local reauthorization contract. This does not expand or prove GitHub API permissions — configure GitHub App permissions with `appPermissions` and in the GitHub App settings for provider-enforced access:
+If you pass `additionalUserScopes`, Junior includes those values in the authorization URL and records the requested scope string as a local reauthorization contract. This does not expand or prove GitHub API permissions. Configure provider-enforced access in the GitHub App settings; `appPermissions` only declares capabilities and controls read-token downscoping:
 
 ```ts
 githubPlugin({
@@ -93,7 +93,7 @@ githubPlugin({
 });
 ```
 
-Use `additionalUserScopes` only when a human-identity integration flow requires specific GitHub OAuth scope parameters in the authorization URL. Do not rely on it to authorize Junior-owned repository or workflow writes — those use repository-scoped installation tokens and the configured GitHub App permissions.
+Use `additionalUserScopes` only when a human-identity integration flow requires specific GitHub OAuth scope parameters in the authorization URL. Do not rely on it to authorize Junior-owned repository or workflow writes — those use repository-scoped installation tokens and the permissions approved on the GitHub App installation.
 
 ## 3) Runtime behavior
 
@@ -128,12 +128,12 @@ new resources through the typed tools, for example
 Use `gh` for the allowlisted lifecycle operations described by the skill.
 
 `gh` supports either direct `GITHUB_TOKEN` (for local debugging) or sandbox-level header injection.
-The plugin uses installation credentials for read-only GitHub traffic, workflow dispatches, allowlisted issue and pull request mutations, and Git smart-HTTP pushes. GitHub App permissions still need to cover the operation: actions for workflow dispatches, issues for issue edits/comments/labels, contents for pushes, pull requests for PR mutations, and workflows for workflow-file pushes.
+The plugin uses installation credentials for read-only GitHub traffic, workflow dispatches, allowlisted issue and pull request mutations, and Git smart-HTTP pushes. The installed GitHub App permissions still need to cover the operation: actions for workflow dispatches, issues for issue edits/comments/labels, contents for pushes, pull requests for PR mutations, and workflows for workflow-file pushes.
 
 Committing and pushing code uses more than one GitHub surface:
 
 - Creating the local Git commit does not call GitHub. Junior sets the GitHub App bot as author and committer and credits resolvable human actors with `Co-Authored-By` trailers.
-- Pushing a branch with Git smart HTTP (`git push`) uses the repository-scoped `installation-write` grant and requires `Contents: write`. If `Workflows: write` is configured, it is included so workflow-file changes can be pushed.
+- Pushing a branch with Git smart HTTP (`git push`) uses the repository-scoped `installation-write` grant and requires the App installation to have `Contents: write`. Workflow-file changes also require the installation to have `Workflows: write`.
 - The smart-HTTP classifier does not distinguish Junior-managed branches or independently detect force updates or ref deletion. Use GitHub branch protection and limit the App installation to repositories where Junior may push.
 - REST Git database and ref writes are denied by the current write allowlist. Use Git smart HTTP (`git push`) for branch updates instead.
 - Opening the PR after the branch exists is separate: `github_createPullRequest` needs pull-request write permission, but it should not create or push commits itself.
@@ -144,10 +144,10 @@ Repository scoping and the egress allowlist are the write boundaries. Credential
 
 Be careful with mixed-surface PR commands. Use the allowlisted REST endpoints
 rather than GraphQL-backed `gh pr` mutation commands. PR-native title, body,
-base, state, ready-for-review, and requested-reviewer changes use the pull
-request grant. Comments, labels, and assignees use GitHub's issue endpoints and
-the issue grant. Merge, branch deletion, REST ref mutation, and administration
-remain unsupported API operations.
+base, state, ready-for-review, and requested-reviewer changes use pull request
+endpoints. Comments, labels, and assignees use GitHub's issue endpoints. All
+allowlisted bot writes share `installation-write`; merge, branch deletion, REST
+ref mutation, and administration remain unsupported API operations.
 
 For PR creation in automation, push explicitly and pass that branch as `head`:
 

package/dist/index.d.ts

@@ -12,11 +12,12 @@ export interface GitHubPluginOptions {
      */
     additionalUserScopes?: string[];
     /**
-     * GitHub App installation permissions Junior should request for app tokens.
+     * GitHub App permissions Junior should expose as capabilities and downscope
+     * to read for installation-read tokens.
      *
      * Keys may use GitHub permission names with underscores or hyphens. Junior
-     * records these as plugin capabilities and requests read-only installation
-     * tokens by scoping read-capable permissions down to `read`.
+     * records these as plugin capabilities. Installation-write tokens inherit
+     * the App installation's complete permission envelope.
      * GitHub remains the source of truth for whether a permission exists.
      */
     appPermissions?: GitHubAppPermissions;

package/dist/index.js

@@ -119,22 +119,24 @@ function sentryConversationUrl(conversationId) {
   const port = parsed.port ? `:${parsed.port}` : "";
   return `${parsed.protocol}//${parsed.hostname}${port}/organizations/${orgSlug}/${path}`;
 }
-function githubConversationFooter(conversationId) {
+function githubConversationFooter(conversationId, dashboardUrl) {
   const id = nonEmptyString(conversationId, "conversationId");
-  const sessionUrl = sentryConversationUrl(id);
+  const normalizedDashboardUrl = dashboardUrl?.trim();
+  const sessionUrl = normalizedDashboardUrl || sentryConversationUrl(id);
   if (!sessionUrl) {
     return void 0;
   }
+  const label = normalizedDashboardUrl ? "View Junior Session" : "View Junior Session in Sentry";
   return `${GITHUB_SESSION_FOOTER_START}
 
 --
 
-[View Junior Session in Sentry](${sessionUrl})
+[${label}](${sessionUrl})
 
 ${GITHUB_SESSION_FOOTER_END}`;
 }
-function appendGitHubFooter(body, conversationId) {
-  const footer = githubConversationFooter(conversationId);
+function appendGitHubFooter(body, conversationId, dashboardUrl) {
+  const footer = githubConversationFooter(conversationId, dashboardUrl);
   const normalizedBody = body.trimEnd();
   const existingFooter = new RegExp(
     `${escapeRegExp(GITHUB_SESSION_FOOTER_START)}[\\s\\S]*?${escapeRegExp(GITHUB_SESSION_FOOTER_END)}`
@@ -645,7 +647,7 @@ function isDefinitiveGitHubPullRequestCreateRejection(error) {
   }
   return [400, 401, 404, 410, 422].includes(error.status);
 }
-function createGitHubPullRequestRequest(conversationId, input, actor) {
+function createGitHubPullRequestRequest(conversationId, input, actor, dashboardUrl) {
   const repo = parseRepo2(input.repo);
   const payload = {
     title: nonEmptyString3(input.title, "title"),
@@ -653,7 +655,8 @@ function createGitHubPullRequestRequest(conversationId, input, actor) {
     base: nonEmptyString3(input.base, "base"),
     body: appendGitHubFooter(
       appendGitHubRequesterAttribution(input.body ?? "", actor),
-      conversationId
+      conversationId,
+      dashboardUrl
     ),
     ...input.draft !== void 0 ? { draft: input.draft } : {}
   };
@@ -788,7 +791,8 @@ function createGitHubPullRequestTool(ctx) {
           const request = createGitHubPullRequestRequest(
             conversationId,
             parsedInput,
-            ctx.actor
+            ctx.actor,
+            ctx.slack?.conversationLink?.url
           );
           const pendingState = {
             status: "pending",
@@ -848,6 +852,7 @@ var USER_REFRESH_TIMEOUT_MS = 2e4;
 var GITHUB_GRAPHQL_RESPONSE_BODY_LIMIT_BYTES = 64 * 1024;
 var HTTP_READ_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
 var USER_TOKEN_GRANTS = /* @__PURE__ */ new Set(["user-read", "user-write"]);
+var CREATE_TOOL_ROUTING_GUIDANCE = "This is a Junior tool-routing denial, not a GitHub permission failure. Do not ask the user for GitHub permissions; retry with the required Junior tool.";
 var USER_WRITE_REQUIREMENTS = [
   "requesting GitHub user permission to perform this operation"
 ];
@@ -1572,17 +1577,16 @@ async function issueInstallationCredential(options) {
     throw new GitHubPluginSetupError(`Invalid ${options.installationIdEnv}`);
   }
   const appJwt = createAppJwt(appId, options.privateKeyEnv);
-  const permissions = options.permissions ?? await options.loadPermissions?.({ appJwt, installationId });
+  const body = "repositories" in options ? { repositories: options.repositories } : {
+    permissions: "permissions" in options ? options.permissions : await options.loadPermissions({ appJwt, installationId })
+  };
   const accessTokenResponse = await githubRequest(
     "https://api.github.com",
     `/app/installations/${installationId}/access_tokens`,
     {
       method: "POST",
       token: appJwt,
-      body: {
-        ...permissions ? { permissions } : {},
-        ...options.repositories ? { repositories: options.repositories } : {}
-      }
+      body
     }
   );
   const parsedToken = parseInstallationTokenResponse(accessTokenResponse);
@@ -1865,7 +1869,7 @@ function assertGitHubWriteAllowed(input) {
     input.bodyText
   )) {
     throw new EgressPolicyDenied(
-      "GitHub issue creation must use the github_createIssue tool so Junior can own idempotency and the conversation footer."
+      `GitHub issue creation must use the github_createIssue tool so Junior can own idempotency and the conversation footer. ${CREATE_TOOL_ROUTING_GUIDANCE}`
     );
   }
   if (isGitHubPullCreateRestRequest(input.method, input.upstreamUrl) || isGitHubPullCreateGraphqlMutation(
@@ -1874,21 +1878,17 @@ function assertGitHubWriteAllowed(input) {
     input.bodyText
   )) {
     throw new EgressPolicyDenied(
-      "GitHub pull request creation must use the github_createPullRequest tool so Junior can own idempotency and the conversation footer."
+      `GitHub pull request creation must use the github_createPullRequest tool so Junior can own idempotency and the conversation footer. ${CREATE_TOOL_ROUTING_GUIDANCE}`
     );
   }
 }
-function grantRequirements(reason) {
-  return reason === "github.user-write" ? USER_WRITE_REQUIREMENTS : void 0;
-}
 function grantForAccess(access, reason, name, leaseScope) {
-  const requirements = grantRequirements(reason);
   return {
     name,
     access,
     ...leaseScope ? { leaseScope } : {},
     reason,
-    ...requirements ? { requirements } : {}
+    ...reason === "github.user-write" ? { requirements: USER_WRITE_REQUIREMENTS } : {}
   };
 }
 function repositoryLeaseScope(upstreamUrl) {
@@ -1971,10 +1971,10 @@ function githubPlugin(options = {}) {
   const appIdEnv = options.appIdEnv ?? GITHUB_APP_ID_ENV;
   const privateKeyEnv = options.privateKeyEnv ?? GITHUB_APP_PRIVATE_KEY_ENV;
   const installationIdEnv = options.installationIdEnv ?? GITHUB_INSTALLATION_ID_ENV;
-  const appPermissions = normalizePermissions(options.appPermissions);
-  const appReadPermissions = appPermissions ? readGrantPermissions(appPermissions) : void 0;
+  const declaredAppPermissions = normalizePermissions(options.appPermissions);
+  const declaredReadPermissions = declaredAppPermissions ? readGrantPermissions(declaredAppPermissions) : void 0;
   const loadReadPermissions = createPermissionCache();
-  const appCapabilities = permissionCapabilities(appPermissions);
+  const appCapabilities = permissionCapabilities(declaredAppPermissions);
   const userScopes = normalizeScopeList(options.additionalUserScopes);
   const userScope = userScopes.length ? userScopes.join(" ") : void 0;
   return defineJuniorPlugin({
@@ -2090,7 +2090,7 @@ function githubPlugin(options = {}) {
               appIdEnv,
               privateKeyEnv,
               installationIdEnv,
-              ...appReadPermissions ? { permissions: appReadPermissions } : { loadPermissions: loadReadPermissions }
+              ...declaredReadPermissions ? { permissions: declaredReadPermissions } : { loadPermissions: loadReadPermissions }
             });
           }
           if (ctx.grant.name === "installation-write") {
@@ -2101,12 +2101,8 @@ function githubPlugin(options = {}) {
               appIdEnv,
               privateKeyEnv,
               installationIdEnv,
-              ...appPermissions ? {
-                permissions: {
-                  ...appPermissions,
-                  metadata: "read"
-                }
-              } : {},
+              // This repository-only variant cannot downscope the installed
+              // App envelope with an operation-specific permission body.
               repositories: [repository.name]
             });
           }

package/dist/permissions.d.ts

@@ -1,6 +1,6 @@
 export type GitHubAppPermissionLevel = "admin" | "read" | "write";
 export type GitHubAppPermissions = Record<string, GitHubAppPermissionLevel>;
-/** Validate configured GitHub App permissions before using them in grants. */
+/** Validate the configured GitHub App capability and read-token declaration. */
 export declare function normalizePermissions(permissions: GitHubAppPermissions | undefined): GitHubAppPermissions | undefined;
 /** Build the read-only installation-token permission body. */
 export declare function readGrantPermissions(permissions: Record<string, unknown> | undefined): Record<string, "read">;

package/dist/tools/footer.d.ts

@@ -1,13 +1,10 @@
 export declare const GITHUB_SESSION_FOOTER_START = "<!-- junior-session-footer:start -->";
 export declare const GITHUB_SESSION_FOOTER_END = "<!-- junior-session-footer:end -->";
 export declare function sentryConversationUrl(conversationId: string): string | undefined;
-/**
- * Build the Junior session footer block for GitHub issues and pull requests.
- * Returns undefined when Sentry DSN/org are not configured.
- */
-export declare function githubConversationFooter(conversationId: string): string | undefined;
+/** Build the Junior session footer, preferring a host-provided dashboard link. */
+export declare function githubConversationFooter(conversationId: string, dashboardUrl?: string): string | undefined;
 /**
  * Append (or replace an existing) Junior session footer to a GitHub body string.
- * When Sentry is not configured, returns the body unchanged (existing footer stripped).
+ * Without a dashboard or Sentry link, returns the body unchanged (existing footer stripped).
  */
-export declare function appendGitHubFooter(body: string, conversationId: string): string;
+export declare function appendGitHubFooter(body: string, conversationId: string, dashboardUrl?: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-github",
-  "version": "0.102.2",
+  "version": "0.103.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -25,7 +25,7 @@
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
     "zod": "^4.4.3",
-    "@sentry/junior-plugin-api": "0.102.2"
+    "@sentry/junior-plugin-api": "0.103.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/skills/github-code/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: github-code
-description: Work with GitHub repositories, source code, branches, commits, pushes, pull requests, reviews, diffs, and CI runs. Use for repo implementation tasks, source-code investigation, cloning/fetching, branch and push workflows, PR creation, PR updates, PR review feedback, and GitHub Actions checks. Prefer this skill for repository and code tasks even when the repo concerns Sentry products.
+description: Work with GitHub repositories, source code, branches, commits, pushes, pull requests, reviews, diffs, CI runs, and GitHub App credentials for branch and PR workflows. Use for repo implementation tasks, source-code investigation, cloning/fetching, branch and push workflows, PR creation or updates, PR review feedback, GitHub credential or permission failures involving repositories, pushes, or PRs, and GitHub Actions checks. Prefer this skill for repository and code tasks even when the repo concerns Sentry products.
 ---
 
 # GitHub Code Operations
 
-Use `gh` and `git` for repository checkout, source investigation, code changes, commits, and pull request inspection or mutation. Use Junior's `github_createPullRequest` tool for new pull requests.
+## Credential contract
+
+- Supported App-owned GitHub operations require no user-managed credential. Junior automatically mints and injects a repository-scoped GitHub App `installation-write` credential.
+- For a pull request from an existing branch, push the branch first, then call `github_createPullRequest`; both operations receive the automatic installation credential.
+- Do not ask the user to authorize GitHub, provide a token, or grant Contents/Pull requests permissions before trying a supported operation.
+- Request remediation only after a supported operation returns evidence of an upstream provider denial. A Junior tool-routing denial means retry with the required tool, not request permissions.
+
+Use `gh` and `git` for repository checkout, source investigation, code changes, commits, and pull request inspection or mutation. Use Junior's `github_createPullRequest` tool instead of `gh pr create` for new pull requests.
 
 ## References
 

package/skills/github-code/references/api-surface.md

@@ -65,9 +65,9 @@ jr-rpc config set github.repo owner/repo
 - Prefer `--json` output for machine-readable parsing where available.
 - Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
 - A local `git commit` does not call GitHub. Pushing that commit uses Junior's repository-scoped installation credential and requires `github.contents.write` on the target repo.
-- If the commit changes workflow files under `.github/workflows`, expect `github.workflows.write` in addition to contents write.
+- If the commit changes workflow files under `.github/workflows`, the App installation needs Workflows write in addition to Contents write.
 - Before `github_createPullRequest`, push the head branch explicitly and resolve the target repo's default branch for `base`. That push requires GitHub write access to the remote.
 - Merge, fork creation, workflow reruns or cancellations, REST contents/Git database writes, and repository administration are outside the current write allowlist.
 - If the explicit `git push` fails with 401/403 or another access/permission error, verify the repo context and retry once. If it still fails, load troubleshooting guidance and report the exact command failure.
-- PR comments, labels, and assignees use GitHub's issue endpoints and therefore the issue grant; use the `github-issues` REST guidance for those operations.
+- PR comments, labels, and assignees use GitHub's issue endpoints; use the `github-issues` REST guidance for those operations. All allowlisted bot writes share the same repository-scoped `installation-write` credential.
 - Return actionable errors for access, permission, not-found, and validation failures.

package/skills/github-code/references/troubleshooting-workarounds.md

@@ -13,9 +13,10 @@ Use this table to recover quickly while keeping operations deterministic.
 | `junior-auth-required provider=github grant=user-write`               | User-to-server OAuth is missing or stale for a human-identity operation.         | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                                                                             |
 | `git push` fails with 401/403 or auth/permission output               | Write permission is missing, app installation is too narrow, or remote is wrong. | Verify the remote and repo context, retry once, then confirm app permissions and installation scope if it still fails.                                                               |
 | Bash result includes `permission_denied` with `source: "upstream"`    | GitHub returned 403 after Junior injected the named grant.                       | Do not call this a Junior runtime block. Use the message, connected account, upstream target, grant requirements, accepted-permissions, and SSO fields to explain the GitHub denial. |
-| 403 Forbidden                                                         | App lacks required permission on repo or install scope is too narrow.            | Verify the repo context, then confirm GitHub App permissions and installation scope.                                                                                                 |
+| 403 without `permission_denied` where `source: "upstream"`            | Junior may have rejected an unsupported route before contacting GitHub.          | Read the response body. Follow any required-tool instruction; do not ask for GitHub permissions unless the failure is confirmed upstream.                                            |
 | `gh auth status` shows `Token scopes: none`                           | Expected for GitHub App user-to-server tokens.                                   | Do not treat this as read-only proof. Use the failed command, `permission_denied.acceptedPermissions`, and GitHub App permissions instead.                                           |
-| `github_createPullRequest` fails with auth/permission errors          | The branch was not pushed first, or repo context is wrong.                       | Push the branch explicitly first, then retry `github_createPullRequest` with explicit `repo`, `head`, and `base` values.                                                             |
+| `github_createPullRequest` returns upstream 401/403                   | The App installation or target repository does not permit the operation.         | Use the structured upstream denial to verify installation scope and accepted permissions; do not request user OAuth for this bot-owned operation.                                    |
+| `github_createPullRequest` returns 422 for `head`                     | The head branch was not pushed or the explicit head ref is wrong.                | Push the branch, then retry with explicit `repo`, `head`, and `base` values.                                                                                                         |
 | `github_createPullRequest` fails with 422 validation on `base`        | The `base` branch does not exist in the target repo.                             | Resolve the default branch with `gh repo view owner/repo --json defaultBranchRef --jq .defaultBranchRef.name`, then retry with that value as `base`.                                 |
 | `git blame`, long log history, or old commits are missing after clone | Repo was cloned shallow by design.                                               | Deepen incrementally with `git -C DIRECTORY fetch --depth=N origin`, or `git -C DIRECTORY fetch --unshallow` when full history is required.                                          |
 | `sandbox setup failed (dnf install gh failed ...)`                    | `gh` package not available from the plugin runtime dependency bootstrap.         | Report the plugin runtime bootstrap failure; do not try to repair package installation from the skill workflow.                                                                      |

package/skills/github-issues/references/troubleshooting-workarounds.md

@@ -2,18 +2,19 @@
 
 Use this table to recover quickly while keeping operations deterministic.
 
-| Symptom                                                 | Likely cause                                                                | Fix                                                                                                                             |
-| ------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `unknown command "issue"` from `gh`                     | CLI version too old or wrong binary in the plugin runtime.                  | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.      |
-| `Missing required option --repo`                        | Repo not passed and no default was resolved.                                | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing.                                 |
-| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                    |
-| `GraphQL: Could not resolve to a Repository`            | Repo slug is wrong or inaccessible.                                         | Validate `owner/repo` and confirm app installation on target repository.                                                        |
-| 401 Unauthorized                                        | Issued GitHub credentials were rejected upstream.                           | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup. |
-| `junior-auth-required provider=github grant=user-write` | User-to-server OAuth is missing or stale for a human-identity operation.    | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                        |
-| 403 Forbidden                                           | App lacks required permission on repo or install scope is too narrow.       | Verify the repo context, then confirm GitHub App permissions and installation scope.                                            |
-| 404 Not Found                                           | Issue number or repo is wrong.                                              | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`.                                                         |
-| Issue label mutation fails                              | Wrong REST payload or wrong repo context.                                   | Use the allowlisted issue labels endpoint with an explicit `owner/repo` path and valid JSON input.                              |
-| Comment command fails with empty body                   | JSON input is missing a non-empty `body`.                                   | Ensure the REST comment payload contains a non-empty `body` before retrying.                                                    |
+| Symptom                                                    | Likely cause                                                                | Fix                                                                                                                                       |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `unknown command "issue"` from `gh`                        | CLI version too old or wrong binary in the plugin runtime.                  | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.                |
+| `Missing required option --repo`                           | Repo not passed and no default was resolved.                                | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing.                                           |
+| Command affects or authenticates against the wrong repo    | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                              |
+| `GraphQL: Could not resolve to a Repository`               | Repo slug is wrong or inaccessible.                                         | Validate `owner/repo` and confirm app installation on target repository.                                                                  |
+| 401 Unauthorized                                           | Issued GitHub credentials were rejected upstream.                           | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup.           |
+| `junior-auth-required provider=github grant=user-write`    | User-to-server OAuth is missing or stale for a human-identity operation.    | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                                  |
+| 403 without `permission_denied` where `source: "upstream"` | Junior may have rejected an unsupported route before contacting GitHub.     | Read the response body. Follow any required-tool instruction; do not ask for GitHub permissions unless the failure is confirmed upstream. |
+| `permission_denied` with `source: "upstream"`              | GitHub rejected the injected installation credential.                       | Verify the target, accepted permissions, and App installation scope; do not request user OAuth for a bot-owned issue operation.           |
+| 404 Not Found                                              | Issue number or repo is wrong.                                              | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`.                                                                   |
+| Issue label mutation fails                                 | Wrong REST payload or wrong repo context.                                   | Use the allowlisted issue labels endpoint with an explicit `owner/repo` path and valid JSON input.                                        |
+| Comment command fails with empty body                      | JSON input is missing a non-empty `body`.                                   | Ensure the REST comment payload contains a non-empty `body` before retrying.                                                              |
 
 ## Retry guidance