@sentry/junior-github 0.93.0 → 0.95.0

package/SETUP.md

@@ -1,6 +1,6 @@
 # GitHub plugin setup
 
-This plugin exposes two skills — `github-code` (clone, source-code investigation, pull requests) and `github-issues` (issue workflows). Read operations use host-issued GitHub App installation tokens. Write operations use GitHub App user-to-server OAuth tokens so GitHub attributes the action to the requesting user with the app badge.
+This plugin exposes two skills — `github-code` (clone, source-code investigation, pull requests) and `github-issues` (issue workflows). Junior uses GitHub App installation tokens for reads, workflow dispatches, allowlisted issue and pull request writes, and Git branch pushes. Human OAuth is reserved for explicitly personal operations such as pull request reviews.
 
 ## 1) Create/install GitHub App
 
@@ -83,7 +83,7 @@ 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.
 
-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. GitHub returns an empty `scope` value for these tokens, so Junior cannot verify granted scopes from the token response.
+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:
 
@@ -93,15 +93,16 @@ githubPlugin({
 });
 ```
 
-Use `additionalUserScopes` only when an integration flow requires specific GitHub OAuth scope parameters in the authorization URL. Do not rely on it to authorize repository, Actions, or workflow writes — those are enforced by GitHub App permissions and the requesting user's own access.
+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.
 
 ## 3) Runtime behavior
 
 - When either GitHub skill is active, authenticated `gh` and `git` commands cause the runtime to inject GitHub credentials automatically for the current turn.
-- The plugin classifies GitHub traffic from the forwarded HTTP request. Safe app-readable API methods, GraphQL `GET`/`HEAD`/`OPTIONS` requests, GraphQL `POST` bodies that prove the operation is a query, and `git-upload-pack` use the `installation-read` grant. `GET /user` uses the `user-read` grant so account identity checks use the actor token. Write-specific REST URLs, GraphQL mutations/subscriptions, unknown GraphQL `POST` bodies, other non-read API methods, and `git-receive-pack` use the `user-write` grant.
-- `user-read` and `user-write` require the actor, or an explicitly delegated user subject from an allowed system run, to authorize the GitHub App through the private OAuth flow. Missing or expired user authorization pauses interactive turns, sends a private authorization link, and resumes after approval.
-- Git commits use the actor as the commit author, Junior as committer, and a Junior `Co-Authored-By` trailer.
-- Issued credentials are reused only within the current turn, credential leases are cached separately by plugin grant name, and upstream 403 permission denials clear the cached lease before the next retry.
+- The plugin classifies GitHub traffic from the forwarded HTTP request. Reads use `installation-read`, while `GET /user` uses `user-read`. Workflow dispatches use the repository-scoped `installation-actions-write` grant. Allowlisted issue and pull request mutations use their own repository-scoped installation grants. Git smart-HTTP pushes use `installation-pr-branch-write`. Unknown REST writes and GraphQL mutations are denied.
+- `user-read` and the remaining explicitly human `user-write` operations require the actor, or an explicitly delegated user subject, to authorize the GitHub App through the private OAuth flow. Junior-owned issue, pull request, and branch operations do not fall back to user OAuth.
+- Headless resource-event turns use the `resource-event` system actor and may receive the same repository-scoped installation grants. This lets Junior respond to subscribed pull request events by committing and pushing fixes without inheriting a subscriber's OAuth credential.
+- Git commits use Junior as author and committer. Resolvable human run actors are credited once with `Co-Authored-By` trailers.
+- Issued credentials are reused only within the current turn, credential leases are cached by plugin grant and repository lease scope, and upstream 403 permission denials clear the cached lease before the next retry.
 - Sandbox does not receive raw tokens via env; host applies Authorization header transforms for GitHub API calls.
 
 ## 4) CLI usage
@@ -121,33 +122,32 @@ git -C repo fetch --depth=50 origin
 git -C repo fetch --unshallow
 ```
 
-Load the relevant GitHub skill for command guidance and repo context:
-
-```bash
-gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sandbox/tmp/issue.md
-```
+Load the relevant GitHub skill for command guidance and repo context. Create
+new resources through the typed tools, for example
+`github_createIssue({ repo: "owner/repo", title: "Example issue", body: "..." })`.
+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-read` for read-only GitHub traffic and `user-write` for mutations. GitHub App permissions still need to cover the operation: issues for issue edits/comments/labels, contents for pushes and merges, pull requests for PR mutations, actions/workflows for workflow operations.
+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.
 
 Committing and pushing code uses more than one GitHub surface:
 
-- Creating the local Git commit does not call GitHub. Junior sets the actor as author and the GitHub App bot as committer in the sandbox.
-- Pushing a branch with Git smart HTTP (`git push`) uses the `user-write` grant and requires the GitHub App to have `Contents: write` on the target repository. The requesting user must also have write access to that repository.
-- REST Git database writes used by some `gh` flows also require `Contents: write`: create blob (`POST /git/blobs`), create tree (`POST /git/trees`), create commit (`POST /git/commits`), and create/update refs (`POST /git/refs`, `PATCH /git/refs/{ref}`). Changes to workflow files may also require `Workflows: write`.
+- 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-pr-branch-write` grant and requires `Contents: write`. If `Workflows: write` is configured, it is included so workflow-file changes can be pushed.
+- 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.
 
-Fork creation is not part of the default PR path. `POST /repos/{owner}/{repo}/forks` uses the `user-write` grant, but GitHub requires `Administration: write` and `Contents: read`, and the app must be installed on both the source and destination accounts. Do not grant `Administration: write` for routine PR creation; push a branch explicitly and create the PR with `github_createPullRequest` instead.
+Fork creation is not part of the default PR path and is denied by the current write allowlist. Do not grant `Administration: write` for routine PR creation; push a branch explicitly and create the PR with `github_createPullRequest` instead.
 
 GitHub App permission scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations, and the host runtime still decides when to mint credentials. Credential injection is provider-domain scoped for sandbox traffic to `api.github.com` and `github.com` during turns with a signed credential context. Keep repo context explicit, and let the plugin choose the required grant for the outbound request.
 
-Be careful with mixed-surface PR commands:
-
-- `gh pr edit` title/body/base/reviewer changes fit `github.pull-requests.write`.
-- `gh pr edit` label changes fit `github.issues.write`.
-- `gh pr edit` assignee/milestone changes fit `github.issues.write`.
-- `gh pr close --comment` may need `github.issues.write`.
-- `gh pr close --delete-branch` needs `github.contents.write`.
+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.
 
 For PR creation in automation, push explicitly and pass that branch as `head`:
 
@@ -192,10 +192,10 @@ jr-rpc config set github.repo getsentry/junior
 2. Confirm the GitHub App is installed on your test repo with the permissions above.
 3. Deploy `main` to prod.
 4. Exercise `github-issues` to create an issue in a safe test repo.
-5. Verify the issue is authored by the requesting GitHub user with the GitHub App badge.
+5. Verify the issue is authored by the GitHub App bot and includes `Requested by` attribution.
 6. Exercise `github-issues` to update title/body, add/remove labels, and add a comment.
 7. Push a test branch and exercise `github-code` to create a draft PR using explicit repo targeting and `--head`.
-8. Verify all mutations succeed and are attributed to the requesting GitHub user with the app badge.
+8. Verify allowlisted mutations are attributed to the GitHub App bot, while a pull request review still requires delegated human authorization.
 9. Verify GitHub API calls succeed while this skill is active without writing tokens into sandbox env/files.
 10. Verify raw token values are never printed in output or logs.
 11. Check logs for:

package/dist/index.js

@@ -150,6 +150,43 @@ function appendGitHubFooter(body, conversationId) {
 ${footer}` : footer;
 }
 
+// src/tool-support/attribution.ts
+var GITHUB_REQUEST_ATTRIBUTION_START = "<!-- junior-request-attribution:start -->";
+var GITHUB_REQUEST_ATTRIBUTION_END = "<!-- junior-request-attribution:end -->";
+function cleanDisplayValue(value) {
+  const cleaned = value?.replace(/[\r\n<>]/g, " ").trim();
+  return cleaned || void 0;
+}
+function actorLabel(actor) {
+  if (!actor) {
+    return void 0;
+  }
+  if (actor.platform === "system") {
+    return `Junior system actor \`${actor.name}\``;
+  }
+  const display = cleanDisplayValue(actor.fullName) ?? cleanDisplayValue(actor.userName) ?? cleanDisplayValue(actor.userId);
+  return display ? `**${display.replaceAll("*", "\\*")}**` : void 0;
+}
+function appendGitHubRequesterAttribution(body, actor) {
+  const label = actorLabel(actor);
+  const attribution = label ? `${GITHUB_REQUEST_ATTRIBUTION_START}
+Requested by ${label} via Junior.
+${GITHUB_REQUEST_ATTRIBUTION_END}` : void 0;
+  const normalizedBody = body.trimEnd();
+  const existing = new RegExp(
+    `${GITHUB_REQUEST_ATTRIBUTION_START}[\\s\\S]*?${GITHUB_REQUEST_ATTRIBUTION_END}`
+  );
+  if (existing.test(normalizedBody)) {
+    return attribution ? normalizedBody.replace(existing, attribution) : normalizedBody.replace(existing, "").trimEnd();
+  }
+  if (!attribution) {
+    return normalizedBody;
+  }
+  return normalizedBody ? `${normalizedBody}
+
+${attribution}` : attribution;
+}
+
 // src/tools/create-issue.ts
 var GITHUB_ISSUE_CREATE_IDEMPOTENCY_TTL_MS = 30 * 24 * 60 * 60 * 1e3;
 var GITHUB_ISSUE_CREATE_LOCK_TTL_MS = 6e4;
@@ -297,14 +334,17 @@ function isDefinitiveGitHubIssueCreateRejection(error) {
   }
   return [400, 401, 404, 410, 422].includes(error.status);
 }
-function createGitHubIssueRequest(conversationId, input) {
+function createGitHubIssueRequest(conversationId, input, actor) {
   const repo = parseRepo(input.repo);
   const labels = input.labels?.map(
     (label) => nonEmptyString2(label, "labels entry")
   );
   const payload = {
     title: nonEmptyString2(input.title, "title"),
-    body: appendGitHubFooter(input.body ?? "", conversationId),
+    body: appendGitHubFooter(
+      appendGitHubRequesterAttribution(input.body ?? "", actor),
+      conversationId
+    ),
     ...labels?.length ? { labels } : {}
   };
   return new Request(
@@ -378,7 +418,11 @@ function createGitHubIssueTool(ctx) {
               "GitHub issue creation for this tool call has an uncertain pending result; refusing to create a duplicate issue."
             );
           }
-          const request = createGitHubIssueRequest(conversationId, parsedInput);
+          const request = createGitHubIssueRequest(
+            conversationId,
+            parsedInput,
+            ctx.actor
+          );
           const pendingState = {
             status: "pending",
             createdAtMs: Date.now()
@@ -601,13 +645,16 @@ function isDefinitiveGitHubPullRequestCreateRejection(error) {
   }
   return [400, 401, 404, 410, 422].includes(error.status);
 }
-function createGitHubPullRequestRequest(conversationId, input) {
+function createGitHubPullRequestRequest(conversationId, input, actor) {
   const repo = parseRepo2(input.repo);
   const payload = {
     title: nonEmptyString3(input.title, "title"),
     head: nonEmptyString3(input.head, "head"),
     base: nonEmptyString3(input.base, "base"),
-    body: appendGitHubFooter(input.body ?? "", conversationId),
+    body: appendGitHubFooter(
+      appendGitHubRequesterAttribution(input.body ?? "", actor),
+      conversationId
+    ),
     ...input.draft !== void 0 ? { draft: input.draft } : {}
   };
   return new Request(
@@ -740,7 +787,8 @@ function createGitHubPullRequestTool(ctx) {
           }
           const request = createGitHubPullRequestRequest(
             conversationId,
-            parsedInput
+            parsedInput,
+            ctx.actor
           );
           const pendingState = {
             status: "pending",
@@ -801,25 +849,20 @@ 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 CONTENTS_WRITE_REQUIREMENTS = [
-  "GitHub App Contents: write on the target repository",
-  "requesting GitHub user write access to the repository"
+  "GitHub App Contents: write on the target repository"
 ];
-var WORKFLOWS_WRITE_REQUIREMENTS = [
-  "GitHub App Contents: write and Workflows: write on the target repository",
-  "requesting GitHub user write access to the repository"
+var ACTIONS_WRITE_REQUIREMENTS = [
+  "GitHub App Actions: write on the target repository"
 ];
 var ISSUES_WRITE_REQUIREMENTS = [
-  "GitHub App Issues: write on the target repository",
-  "requesting GitHub user issue access to the repository"
+  "GitHub App Issues: write on the target repository"
 ];
 var PULL_REQUESTS_WRITE_REQUIREMENTS = [
-  "GitHub App Pull requests: write on the target repository",
-  "requesting GitHub user write access to the repository"
+  "GitHub App Pull requests: write on the target repository"
 ];
-var FORK_CREATE_REQUIREMENTS = [
-  "GitHub App Administration: write and Contents: read",
-  "app installation access on the source and destination accounts",
-  "requesting GitHub user permission to fork the repository"
+var PULL_REVIEW_WRITE_REQUIREMENTS = [
+  ...PULL_REQUESTS_WRITE_REQUIREMENTS,
+  "requesting GitHub user permission to review the pull request"
 ];
 var GitHubUserRefreshRejectedError = class extends Error {
   constructor(message) {
@@ -920,14 +963,12 @@ function additionalActorCoauthorTrailers(args) {
   if (!args.actors || args.actors.length === 0) {
     return [];
   }
-  const runActorKey = args.runActor ? actorIdentityKey(args.runActor) : void 0;
   const seenEmails = /* @__PURE__ */ new Set([args.botEmail.toLowerCase()]);
-  if (args.authorEmail) {
-    seenEmails.add(args.authorEmail.toLowerCase());
-  }
+  const seenActors = /* @__PURE__ */ new Set();
   const trailers = [];
   for (const candidate of args.actors) {
-    if (runActorKey && actorIdentityKey(candidate) === runActorKey) {
+    const actorKey = actorIdentityKey(candidate);
+    if (seenActors.has(actorKey)) {
       continue;
     }
     const name = actorName(candidate);
@@ -939,6 +980,7 @@ function additionalActorCoauthorTrailers(args) {
     if (seenEmails.has(emailKey)) {
       continue;
     }
+    seenActors.add(actorKey);
     seenEmails.add(emailKey);
     trailers.push(`Co-Authored-By: ${name} <${email}>`);
   }
@@ -954,23 +996,18 @@ if [ -z "$message_file" ]; then
 fi
 
 if [ -z "\${JUNIOR_GIT_AUTHOR_NAME:-}" ] || [ -z "\${JUNIOR_GIT_AUTHOR_EMAIL:-}" ]; then
-  echo "Junior GitHub plugin internal error: actor commit attribution was not injected by the host runtime. Do not set Git author env vars manually; report this configuration error." >&2
+  echo "Junior GitHub plugin internal error: Junior author identity was not injected by the host runtime. Do not set Git author env vars manually; report this configuration error." >&2
   exit 1
 fi
 
 if [ "\${GIT_AUTHOR_NAME:-}" != "$JUNIOR_GIT_AUTHOR_NAME" ] || [ "\${GIT_AUTHOR_EMAIL:-}" != "$JUNIOR_GIT_AUTHOR_EMAIL" ]; then
-  echo "Junior GitHub plugin internal error: Git author was not set to the resolved actor identity. Do not override Git author manually; report this configuration error." >&2
-  exit 1
-fi
-
-if [ -z "\${JUNIOR_GIT_COAUTHOR_NAME:-}" ] || [ -z "\${JUNIOR_GIT_COAUTHOR_EMAIL:-}" ]; then
-  echo "Junior GitHub plugin internal error: Junior coauthor identity was not injected by the host runtime. Do not set coauthor env vars manually; report this configuration error." >&2
+  echo "Junior GitHub plugin internal error: Git author was not set to the Junior identity. Do not override Git author manually; report this configuration error." >&2
   exit 1
 fi
 
 # Git and GitHub only interpret the final contiguous paragraph as the trailer
 # block, so all missing trailers are collected and appended as one block:
-# actor trailers in order, Junior's agent trailer last.
+# human actor trailers in run order.
 desired_trailers=""
 add_trailer() {
   desired_trailers="$desired_trailers$1"$'\\n'
@@ -984,8 +1021,6 @@ if [ -n "\${JUNIOR_GIT_ACTOR_COAUTHOR_TRAILERS:-}" ]; then
   done <<< "$JUNIOR_GIT_ACTOR_COAUTHOR_TRAILERS"
 fi
 
-add_trailer "Co-Authored-By: $JUNIOR_GIT_COAUTHOR_NAME <$JUNIOR_GIT_COAUTHOR_EMAIL>"
-
 final_trailer_block=$(awk '
   { lines[NR] = $0 }
   END {
@@ -1011,6 +1046,57 @@ final_trailer_block=$(awk '
   }
 ' "$message_file")
 
+duplicate_desired_trailer=false
+while IFS= read -r desired_trailer; do
+  if [ -n "$desired_trailer" ] && [ "$(printf '%s\\n' "$final_trailer_block" | grep -Fxc -- "$desired_trailer")" -gt 1 ]; then
+    duplicate_desired_trailer=true
+    break
+  fi
+done <<< "$desired_trailers"
+
+if [ "$duplicate_desired_trailer" = true ]; then
+  tmp_file=$(mktemp)
+  desired_file=$(mktemp)
+  trap 'rm -f "$tmp_file" "$desired_file"' EXIT
+  printf '%s' "$desired_trailers" > "$desired_file"
+  awk -v desired_file="$desired_file" '
+    BEGIN {
+      while ((getline value < desired_file) > 0) {
+        if (value != "") {
+          wanted[value] = 1
+        }
+      }
+      close(desired_file)
+    }
+    { lines[NR] = $0 }
+    END {
+      line = NR
+      while (line > 0 && lines[line] == "") {
+        line--
+      }
+      start = line
+      while (start > 0 && lines[start] != "") {
+        start--
+      }
+      valid = line > 0
+      for (i = start + 1; valid && i <= line; i++) {
+        if (lines[i] !~ /^[[:alnum:]-]+: .+/) {
+          valid = 0
+        }
+      }
+      for (i = 1; i <= NR; i++) {
+        if (valid && i > start && i <= line && wanted[lines[i]]) {
+          if (seen[lines[i]]++) {
+            continue
+          }
+        }
+        print lines[i]
+      }
+    }
+  ' "$message_file" > "$tmp_file"
+  cat "$tmp_file" > "$message_file"
+fi
+
 missing_trailers=""
 collect_missing_trailer() {
   if ! printf '%s\\n' "$final_trailer_block" | grep -Fqx -- "$1"; then
@@ -1032,18 +1118,7 @@ if [ -n "$(tail -c 1 "$message_file")" ]; then
   printf '\\n' >> "$message_file"
 fi
 
-# When the message already ends with Junior's bot trailer, insert missing
-# actor trailers before it so the bot trailer stays last.
-last_line=$(tail -n 1 "$message_file")
-bot_trailer="Co-Authored-By: $JUNIOR_GIT_COAUTHOR_NAME <$JUNIOR_GIT_COAUTHOR_EMAIL>"
-if [ "$last_line" = "$bot_trailer" ]; then
-  tmp_file=$(mktemp)
-  trap 'rm -f "$tmp_file"' EXIT
-  sed '$d' "$message_file" > "$tmp_file"
-  printf '%s' "$missing_trailers" >> "$tmp_file"
-  printf '%s\\n' "$bot_trailer" >> "$tmp_file"
-  cat "$tmp_file" > "$message_file"
-elif [ -n "$final_trailer_block" ]; then
+if [ -n "$final_trailer_block" ]; then
   printf '%s' "$missing_trailers" >> "$message_file"
 else
   printf '\\n%s' "$missing_trailers" >> "$message_file"
@@ -1298,6 +1373,41 @@ function readInstallationPermissions(installation) {
   }
   return readGrantPermissions(installation.permissions);
 }
+function decodeGitHubPathSegment(value) {
+  try {
+    const decoded = decodeURIComponent(value).trim();
+    return decoded && !decoded.includes("/") ? decoded : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function githubRepositoryFromUrl(upstreamUrl) {
+  const segments = upstreamUrl.pathname.split("/").filter(Boolean);
+  if (isGitHubApiUrl(upstreamUrl) && segments[0]?.toLowerCase() === "repos") {
+    const owner2 = segments[1] ? decodeGitHubPathSegment(segments[1]) : void 0;
+    const name2 = segments[2] ? decodeGitHubPathSegment(segments[2]) : void 0;
+    return owner2 && name2 ? { owner: owner2, name: name2 } : void 0;
+  }
+  if (upstreamUrl.hostname.toLowerCase() !== "github.com") {
+    return void 0;
+  }
+  const owner = segments[0] ? decodeGitHubPathSegment(segments[0]) : void 0;
+  const rawName = segments[1]?.replace(/\.git$/i, "");
+  const name = rawName ? decodeGitHubPathSegment(rawName) : void 0;
+  return owner && name ? { owner, name } : void 0;
+}
+function githubRepositoryLeaseScope(repository) {
+  return `repository:${repository.owner.toLowerCase()}/${repository.name.toLowerCase()}`;
+}
+function githubRepositoryFromLeaseScope(leaseScope) {
+  const match = /^repository:([^/]+)\/([^/]+)$/.exec(leaseScope ?? "");
+  if (!match?.[1] || !match[2]) {
+    throw new GitHubPluginSetupError(
+      "GitHub installation write grant is missing a repository lease scope."
+    );
+  }
+  return { owner: match[1], name: match[2] };
+}
 async function resolveUserAccount(tokens) {
   const account = await githubRequest("https://api.github.com", "/user", {
     token: tokens.accessToken
@@ -1475,12 +1585,11 @@ async function issueInstallationCredential(options) {
     throw new GitHubPluginSetupError(`Invalid ${options.installationIdEnv}`);
   }
   const appJwt = createAppJwt(appId, options.privateKeyEnv);
-  let tokenPermissions = options.readPermissions;
-  if (!tokenPermissions) {
-    tokenPermissions = await options.loadReadPermissions({
-      appJwt,
-      installationId
-    });
+  const permissions = options.permissions ?? await options.loadPermissions?.({ appJwt, installationId });
+  if (!permissions) {
+    throw new GitHubPluginSetupError(
+      "GitHub installation credential permissions are not configured."
+    );
   }
   const accessTokenResponse = await githubRequest(
     "https://api.github.com",
@@ -1488,7 +1597,10 @@ async function issueInstallationCredential(options) {
     {
       method: "POST",
       token: appJwt,
-      body: { permissions: tokenPermissions }
+      body: {
+        permissions,
+        ...options.repositories ? { repositories: options.repositories } : {}
+      }
     }
   );
   const parsedToken = parseInstallationTokenResponse(accessTokenResponse);
@@ -1678,18 +1790,42 @@ function githubApiWriteReason(method, upstreamUrl) {
   if (!isGitHubApiUrl(upstreamUrl)) {
     return void 0;
   }
+  if (method === "POST" && /^\/repos\/[^/]+\/[^/]+\/actions\/workflows\/[^/]+\/dispatches$/.test(
+    pathname
+  )) {
+    return "github.actions-workflow-dispatch";
+  }
   if (method === "POST" && /^\/repos\/[^/]+\/[^/]+\/issues$/.test(pathname)) {
     return "github.issue-create";
   }
   if (method === "POST" && /^\/repos\/[^/]+\/[^/]+\/issues\/[^/]+\/comments$/.test(pathname)) {
     return "github.issues-write";
   }
+  if (method === "PATCH" && /^\/repos\/[^/]+\/[^/]+\/issues\/[^/]+$/.test(pathname)) {
+    return "github.issues-write";
+  }
+  if ((method === "POST" || method === "DELETE") && /^\/repos\/[^/]+\/[^/]+\/issues\/[^/]+\/(labels|assignees)(?:\/[^/]+)?$/.test(
+    pathname
+  )) {
+    return "github.issues-write";
+  }
   if (method === "POST" && /^\/repos\/[^/]+\/[^/]+\/pulls$/.test(pathname)) {
     return "github.pull-create";
   }
   if (method === "PATCH" && /^\/repos\/[^/]+\/[^/]+\/pulls\/[^/]+$/.test(pathname)) {
     return "github.pull-requests-write";
   }
+  if (method === "POST" && /^\/repos\/[^/]+\/[^/]+\/pulls\/[^/]+\/ready_for_review$/.test(pathname)) {
+    return "github.pull-requests-write";
+  }
+  if ((method === "POST" || method === "DELETE") && /^\/repos\/[^/]+\/[^/]+\/pulls\/[^/]+\/requested_reviewers$/.test(pathname)) {
+    return "github.pull-requests-write";
+  }
+  if (/^\/repos\/[^/]+\/[^/]+\/pulls\/[^/]+\/reviews(?:\/[^/]+(?:\/(events|dismissals))?)?$/.test(
+    pathname
+  ) && !HTTP_READ_METHODS.has(method)) {
+    return "github.pull-review-write";
+  }
   if (method === "POST" && /^\/repos\/[^/]+\/[^/]+\/forks$/.test(pathname)) {
     return "github.fork-create";
   }
@@ -1779,32 +1915,73 @@ function assertGitHubWriteAllowed(input) {
   }
 }
 function grantRequirements(reason) {
+  if (reason === "github.actions-workflow-dispatch") {
+    return ACTIONS_WRITE_REQUIREMENTS;
+  }
   if (reason === "github.git-write" || reason === "github.contents-write") {
     return CONTENTS_WRITE_REQUIREMENTS;
   }
-  if (reason === "github.workflows-write") {
-    return WORKFLOWS_WRITE_REQUIREMENTS;
-  }
   if (reason === "github.issue-create" || reason === "github.issues-write") {
     return ISSUES_WRITE_REQUIREMENTS;
   }
+  if (reason === "github.pull-review-write") {
+    return PULL_REVIEW_WRITE_REQUIREMENTS;
+  }
   if (reason === "github.pull-create" || reason === "github.pull-requests-write") {
     return PULL_REQUESTS_WRITE_REQUIREMENTS;
   }
-  if (reason === "github.fork-create") {
-    return FORK_CREATE_REQUIREMENTS;
-  }
   return void 0;
 }
-function grantForAccess(access, reason, name) {
+function grantForAccess(access, reason, name, leaseScope) {
   const requirements = grantRequirements(reason);
   return {
     name,
     access,
+    ...leaseScope ? { leaseScope } : {},
     reason,
     ...requirements ? { requirements } : {}
   };
 }
+function repositoryLeaseScope(upstreamUrl) {
+  const repository = githubRepositoryFromUrl(upstreamUrl);
+  if (!repository) {
+    throw new EgressPolicyDenied(
+      "GitHub write request does not identify a target repository."
+    );
+  }
+  return githubRepositoryLeaseScope(repository);
+}
+function installationGrantForWrite(reason, upstreamUrl) {
+  const leaseScope = repositoryLeaseScope(upstreamUrl);
+  if (reason === "github.actions-workflow-dispatch") {
+    return grantForAccess(
+      "write",
+      reason,
+      "installation-actions-write",
+      leaseScope
+    );
+  }
+  if (reason === "github.issue-create" || reason === "github.issues-write") {
+    return grantForAccess(
+      "write",
+      reason,
+      "installation-issues-write",
+      leaseScope
+    );
+  }
+  if (reason === "github.pull-create" || reason === "github.pull-requests-write") {
+    return grantForAccess(
+      "write",
+      reason,
+      "installation-pull-requests-write",
+      leaseScope
+    );
+  }
+  if (reason === "github.pull-review-write") {
+    return grantForAccess("write", reason, "user-write", leaseScope);
+  }
+  return void 0;
+}
 async function githubGrantForEgress(ctx) {
   const method = ctx.request.method.toUpperCase();
   const upstreamUrl = new URL(ctx.request.url);
@@ -1816,10 +1993,18 @@ async function githubGrantForEgress(ctx) {
   });
   const smartHttpAccess = githubSmartHttpAccess(upstreamUrl);
   if (smartHttpAccess) {
+    if (smartHttpAccess === "write") {
+      return grantForAccess(
+        "write",
+        "github.git-write",
+        "installation-pr-branch-write",
+        repositoryLeaseScope(upstreamUrl)
+      );
+    }
     return grantForAccess(
       smartHttpAccess,
-      smartHttpAccess === "write" ? "github.git-write" : "github.git-read",
-      smartHttpAccess === "write" ? "user-write" : "installation-read"
+      "github.git-read",
+      "installation-read"
     );
   }
   const userReadReason = githubUserReadReason(method, upstreamUrl);
@@ -1828,7 +2013,13 @@ async function githubGrantForEgress(ctx) {
   }
   const writeReason = githubApiWriteReason(method, upstreamUrl);
   if (writeReason) {
-    return grantForAccess("write", writeReason, "user-write");
+    const grant = installationGrantForWrite(writeReason, upstreamUrl);
+    if (grant) {
+      return grant;
+    }
+    throw new EgressPolicyDenied(
+      `GitHub write operation ${writeReason} is not enabled for Junior credentials.`
+    );
   }
   const graphqlAccess = githubGraphqlAccess(
     method,
@@ -1836,18 +2027,55 @@ async function githubGrantForEgress(ctx) {
     ctx.request.bodyText
   );
   if (graphqlAccess) {
+    if (graphqlAccess === "write") {
+      throw new EgressPolicyDenied(
+        "GitHub GraphQL mutations are not enabled for Junior credentials."
+      );
+    }
     return grantForAccess(
       graphqlAccess,
-      graphqlAccess === "write" ? "github.graphql-write" : "github.graphql-read",
-      graphqlAccess === "write" ? "user-write" : "installation-read"
+      "github.graphql-read",
+      "installation-read"
     );
   }
   const access = HTTP_READ_METHODS.has(method) ? "read" : "write";
-  return grantForAccess(
-    access,
-    access === "write" ? "github.api-write" : "github.api-read",
-    access === "write" ? "user-write" : "installation-read"
-  );
+  if (access === "write") {
+    throw new EgressPolicyDenied(
+      "GitHub write request is not an explicitly allowed Junior operation."
+    );
+  }
+  return grantForAccess(access, "github.api-read", "installation-read");
+}
+function configuredWritePermission(appPermissions, permission) {
+  const level = appPermissions?.[permission];
+  if (level !== void 0 && level !== "write" && level !== "admin") {
+    throw new GitHubPluginSetupError(
+      `githubPlugin appPermissions.${permission} must allow write access for Junior-owned GitHub resources.`
+    );
+  }
+  return {
+    metadata: "read",
+    [permission]: "write"
+  };
+}
+function configuredBranchWritePermissions(appPermissions) {
+  const contents = appPermissions?.contents;
+  if (contents !== void 0 && contents !== "write" && contents !== "admin") {
+    throw new GitHubPluginSetupError(
+      "githubPlugin appPermissions.contents must allow write access for Junior-managed pull request branches."
+    );
+  }
+  const workflows = appPermissions?.workflows;
+  if (workflows !== void 0 && workflows !== "write" && workflows !== "admin") {
+    throw new GitHubPluginSetupError(
+      "githubPlugin appPermissions.workflows must allow write access when configured."
+    );
+  }
+  return {
+    contents: "write",
+    metadata: "read",
+    ...workflows === "write" || workflows === "admin" ? { workflows: "write" } : {}
+  };
 }
 function githubPlugin(options = {}) {
   const botNameEnv = options.botNameEnv ?? "GITHUB_APP_BOT_NAME";
@@ -1933,23 +2161,15 @@ function githubPlugin(options = {}) {
         if (!botName || !botEmail) {
           return;
         }
-        const authorName = actorName(ctx.actor);
-        const authorEmail = actorEmail(ctx.actor);
-        if (authorName && authorEmail) {
-          ctx.env.set("GIT_AUTHOR_NAME", authorName);
-          ctx.env.set("GIT_AUTHOR_EMAIL", authorEmail);
-          ctx.env.set("JUNIOR_GIT_AUTHOR_NAME", authorName);
-          ctx.env.set("JUNIOR_GIT_AUTHOR_EMAIL", authorEmail);
-        }
+        ctx.env.set("GIT_AUTHOR_NAME", botName);
+        ctx.env.set("GIT_AUTHOR_EMAIL", botEmail);
+        ctx.env.set("JUNIOR_GIT_AUTHOR_NAME", botName);
+        ctx.env.set("JUNIOR_GIT_AUTHOR_EMAIL", botEmail);
         ctx.env.set("GIT_COMMITTER_NAME", botName);
         ctx.env.set("GIT_COMMITTER_EMAIL", botEmail);
-        ctx.env.set("JUNIOR_GIT_COAUTHOR_NAME", botName);
-        ctx.env.set("JUNIOR_GIT_COAUTHOR_EMAIL", botEmail);
         const actorTrailers = additionalActorCoauthorTrailers({
-          actors: ctx.actors,
-          authorEmail,
-          botEmail,
-          runActor: ctx.actor
+          actors: [...ctx.actor ? [ctx.actor] : [], ...ctx.actors ?? []],
+          botEmail
         });
         ctx.env.set(
           "JUNIOR_GIT_ACTOR_COAUTHOR_TRAILERS",
@@ -1984,8 +2204,35 @@ function githubPlugin(options = {}) {
               appIdEnv,
               privateKeyEnv,
               installationIdEnv,
-              readPermissions: appReadPermissions,
-              loadReadPermissions
+              ...appReadPermissions ? { permissions: appReadPermissions } : { loadPermissions: loadReadPermissions }
+            });
+          }
+          if (ctx.grant.name === "installation-actions-write" || ctx.grant.name === "installation-issues-write" || ctx.grant.name === "installation-pull-requests-write") {
+            const repository = githubRepositoryFromLeaseScope(
+              ctx.grant.leaseScope
+            );
+            const permission = ctx.grant.name === "installation-actions-write" ? "actions" : ctx.grant.name === "installation-issues-write" ? "issues" : "pull_requests";
+            return await issueInstallationCredential({
+              appIdEnv,
+              privateKeyEnv,
+              installationIdEnv,
+              permissions: configuredWritePermission(
+                appPermissions,
+                permission
+              ),
+              repositories: [repository.name]
+            });
+          }
+          if (ctx.grant.name === "installation-pr-branch-write") {
+            const repository = githubRepositoryFromLeaseScope(
+              ctx.grant.leaseScope
+            );
+            return await issueInstallationCredential({
+              appIdEnv,
+              privateKeyEnv,
+              installationIdEnv,
+              permissions: configuredBranchWritePermissions(appPermissions),
+              repositories: [repository.name]
             });
           }
           if (USER_TOKEN_GRANTS.has(ctx.grant.name)) {

package/dist/tool-support/attribution.d.ts

@@ -0,0 +1,5 @@
+import type { Actor } from "@sentry/junior-plugin-api";
+export declare const GITHUB_REQUEST_ATTRIBUTION_START = "<!-- junior-request-attribution:start -->";
+export declare const GITHUB_REQUEST_ATTRIBUTION_END = "<!-- junior-request-attribution:end -->";
+/** Append or replace runtime-owned requester attribution in a GitHub body. */
+export declare function appendGitHubRequesterAttribution(body: string, actor: Actor | undefined): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-github",
-  "version": "0.93.0",
+  "version": "0.95.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.93.0"
+    "@sentry/junior-plugin-api": "0.95.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/skills/github-code/SKILL.md

@@ -66,6 +66,8 @@ Rules:
 - After a failed fix attempt or strong correction, stop patching symptoms — re-read the evidence and restate the root cause before editing again.
 - If the task is investigation-only, answer from evidence without editing.
 
+**Advisor planning checkpoint:** For a non-trivial implementation — especially architecture or API changes, security-sensitive behavior, concurrency, migrations, broad cross-file edits, or work following failed attempts — call the advisor after gathering enough evidence and before editing. Provide the requirements, relevant code and output, constraints, proposed plan, alternatives considered, risks, and intended validation path. Resolve or explicitly account for material concerns before implementing.
+
 ### 3. Edit safely
 
 - Smallest coherent change that satisfies the request.
@@ -79,8 +81,6 @@ Rules:
 
 For multi-step or risky work, keep a compact checklist of intent, touched files, verification state, next step, and blockers.
 
-For non-obvious architecture, security-sensitive, concurrency, or repeated-failure work, pause after investigation with evidence, risks, and a proposed plan before pushing ahead.
-
 ### 4. Verify before packaging
 
 Before committing and creating a PR for code, config, or docs-as-code changes:
@@ -89,6 +89,8 @@ Before committing and creating a PR for code, config, or docs-as-code changes:
 - For docs or instruction-only changes, do a content consistency review instead of claiming automated validation.
 - If no credible check exists, say so explicitly.
 
+**Advisor review checkpoint:** For a non-trivial implementation, call the advisor after inspecting the final diff and running the initial validation path, but before committing, opening or updating a PR, or reporting completion. Provide the diff, relevant surrounding code, requirements, validation results, known limitations, and any remaining risks. Ask specifically for correctness issues, regressions, missed cases, and testing gaps. Investigate material findings, revise as needed, and rerun affected checks before packaging.
+
 ### 5. Commit
 
 Default format when the repo does not specify otherwise:
@@ -159,11 +161,13 @@ Before finishing, reconcile any plan or checklist stated earlier — mark items
 
 **PR inspection** — read-only `gh pr` and `gh api` commands. Query both conversation comments (`--json comments`) and review comments (`gh api .../pulls/{n}/comments` and `.../reviews`).
 
-**PR mutation** — push before create. Retry once on permission failure after verifying repo targeting. Treat merge, close-with-delete, and force-push as confirmation-required. No admin mutations.
+**PR mutation** — push before create. Use only the allowlisted REST endpoints in the API reference. Merge, close-with-delete, REST ref mutation, and admin operations are unsupported. Git smart HTTP does not independently prevent force updates or ref deletion; rely on GitHub rulesets and do not request destructive pushes.
+
+**Workflow dispatch** — `gh workflow run` is supported for workflows that declare `workflow_dispatch`. Workflow reruns, cancellations, and other Actions mutations remain unsupported.
 
 ## Guardrails
 
 - Default shallow clones; deepen only when needed.
-- Confirm before destructive merges or force operations.
+- Do not attempt destructive merges, force pushes, or ref deletion.
 - Answer source questions from repo evidence, not product framing or memory.
 - Stop and return concrete remediation on missing access or permissions.

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

@@ -1,6 +1,6 @@
 # GitHub API Surface — code & pull requests
 
-PR creation uses Junior's `github_createPullRequest` tool. Other operations use `gh` CLI and must be deterministic and non-interactive.
+PR creation uses Junior's `github_createPullRequest` tool. Supported mutations use allowlisted REST endpoints through `gh api`; generic GraphQL-backed `gh pr` mutations are not supported.
 
 ## Repo scoping
 
@@ -10,16 +10,15 @@ Treat explicit repo flags as command-targeting safety rails, not as a credential
 
 ## GitHub App permission guidance
 
-| Permission capability                                  | Commands                                                                             |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
-| `github.actions.read`                                  | `gh run list`, `gh run view`, `gh run watch`, `gh workflow list`, `gh workflow view` |
-| `github.actions.write`                                 | `gh workflow run`, `gh run rerun`, `gh run cancel`                                   |
-| `github.contents.read`                                 | `gh repo clone`, `git fetch`                                                         |
-| `github.contents.write`                                | `git push`, REST Git database writes, `gh api` create/update contents, `gh pr merge` |
-| `github.workflows.write`                               | Workflow-file changes under `.github/workflows`                                      |
-| `github.pull-requests.read`                            | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks`                             |
-| `github.pull-requests.write`                           | `github_createPullRequest` after explicit push, `gh pr edit`, `gh pr close`          |
-| `github.administration.write` + `github.contents.read` | `gh repo fork`; avoid for routine PR creation                                        |
+| Permission capability        | Commands                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `github.actions.read`        | `gh run list`, `gh run view`, `gh run watch`, `gh workflow list`, `gh workflow view` |
+| `github.actions.write`       | `gh workflow run` only                                                               |
+| `github.contents.read`       | `gh repo clone`, `git fetch`                                                         |
+| `github.contents.write`      | Git smart-HTTP `git push` only                                                       |
+| `github.workflows.write`     | Workflow-file changes carried by Git smart-HTTP push                                 |
+| `github.pull-requests.read`  | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks`                             |
+| `github.pull-requests.write` | Typed PR creation and allowlisted REST PR lifecycle endpoints                        |
 
 ## Command matrix
 
@@ -36,17 +35,20 @@ Treat explicit repo flags as command-targeting safety rails, not as a credential
 | Create branch                      | `git -C DIRECTORY checkout -b BRANCH`                                                                                    |
 | Stage and commit                   | `git -C DIRECTORY add -A && git -C DIRECTORY commit -m "message"`                                                        |
 | Push branch before PR creation     | `git -C DIRECTORY push -u origin BRANCH`                                                                                 |
+| Dispatch workflow                  | `gh workflow run WORKFLOW --repo owner/repo --ref REF [-f key=value]`                                                    |
 | Create pull request (draft)        | `github_createPullRequest({ repo: "owner/repo", head: "BRANCH", base: "BASE", title: "...", body: "...", draft: true })` |
-| Update pull request                | `gh pr edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]`                                                 |
-| Close pull request                 | `gh pr close NUMBER --repo owner/repo`                                                                                   |
-| Merge pull request                 | `gh pr merge NUMBER --repo owner/repo [--merge \| --squash \| --rebase]`                                                 |
+| Update pull request                | `gh api repos/owner/repo/pulls/NUMBER --method PATCH --input payload.json`                                               |
+| Mark ready for review              | `gh api repos/owner/repo/pulls/NUMBER/ready_for_review --method POST`                                                    |
+| Request reviewers                  | `gh api repos/owner/repo/pulls/NUMBER/requested_reviewers --method POST --input reviewers.json`                          |
+| Remove requested reviewers         | `gh api repos/owner/repo/pulls/NUMBER/requested_reviewers --method DELETE --input reviewers.json`                        |
+| Close pull request                 | `gh api repos/owner/repo/pulls/NUMBER --method PATCH -f state=closed`                                                    |
+| Submit human review                | `gh api repos/owner/repo/pulls/NUMBER/reviews --method POST --input review.json`                                         |
 | View pull request                  | `gh pr view NUMBER --repo owner/repo [--json ...]`                                                                       |
 | List pull requests                 | `gh pr list --repo owner/repo [--state open \| closed \| merged]`                                                        |
 | Diff pull request                  | `gh pr diff NUMBER --repo owner/repo`                                                                                    |
 | Check pull request status          | `gh pr checks NUMBER --repo owner/repo`                                                                                  |
 | View PR review comments            | `gh api repos/{owner}/{repo}/pulls/{number}/comments`                                                                    |
 | View PR reviews                    | `gh api repos/{owner}/{repo}/pulls/{number}/reviews`                                                                     |
-| Dispatch workflow                  | `gh workflow run WORKFLOW -R owner/repo --ref REF [-f key=value ...]`                                                    |
 | List workflow runs                 | `gh run list -R owner/repo --workflow WORKFLOW [--limit N] [--json ...]`                                                 |
 | View workflow run                  | `gh run view RUN_ID -R owner/repo [--json ...] [--log-failed]`                                                           |
 | Watch workflow run                 | `gh run watch RUN_ID -R owner/repo --exit-status`                                                                        |
@@ -62,12 +64,10 @@ 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 does: `git push` requires `github.contents.write` on the target repo and actor write access.
-- REST Git commit construction also requires `github.contents.write`: `POST /git/blobs`, `POST /git/trees`, `POST /git/commits`, `POST /git/refs`, and `PATCH /git/refs/{ref}`.
+- 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.
 - 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.
-- Do not use fork creation as the normal PR path. GitHub requires Administration write plus Contents read for `POST /repos/{owner}/{repo}/forks`, and the app must be installed on both source and destination accounts.
+- 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.
-- `gh pr edit` is not a single-permission command: title/body/base/reviewer changes need pull request write permission; label, assignee, and milestone changes need issue write permission (use the `github-issues` skill); project flags are outside the current GitHub App permission guidance.
-- `gh pr close --comment` may need `github.issues.write` (use `github-issues`); `gh pr close --delete-branch` needs `github.contents.write`.
+- PR comments, labels, and assignees use GitHub's issue endpoints and therefore the issue grant; use the `github-issues` REST guidance for those operations.
 - Return actionable errors for access, permission, not-found, and validation failures.

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

@@ -10,7 +10,7 @@ Use this table to recover quickly while keeping operations deterministic.
 | 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 write request.                    | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                                                                             |
+| `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.                                                                                                 |
@@ -24,7 +24,7 @@ Use this table to recover quickly while keeping operations deterministic.
 
 - Retry once for transient transport failures after verifying repo context.
 - Do not loop retries on repeated 401/403/404 validation errors.
-- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work; treat `installation-read` failures as app installation or host environment setup.
+- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work. Treat all `installation-*` failures as App permission, installation scope, or host environment setup; they do not fall back to user OAuth.
 - Do not describe `permission_denied` with `source: "upstream"` as Junior blocking the request. It means the egress proxy injected a credential, forwarded the request, and recorded GitHub's upstream 403. Prefer its `account` and `grant.requirements` fields over inference when explaining what to fix.
 - Do not infer permission level from OAuth scopes. GitHub App user tokens report no OAuth scopes; GitHub App permissions and accepted-permissions headers are the useful evidence.
 - For persistent permission problems, return explicit remediation and stop.

package/skills/github-issues/SKILL.md

@@ -62,7 +62,7 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
 
 **Source attribution:**
 
-- GitHub records the issue creator natively; do not add body or footer text to identify who asked Junior to create the issue.
+- The runtime adds the verified `Requested by` block. Do not add or rewrite requester attribution in model-authored body text.
 - If the person who originally reported or observed the problem differs from the issue creator, capture that with durable body text such as `Reported by Alice.` or `Raised by Alice during incident triage.`
 - Attach screenshots from the thread as image links when present.
 - Include code snippets, related issues, and related PRs only when they materially improve the issue.

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

@@ -1,6 +1,6 @@
 # GitHub Issue API Surface
 
-Issue creation uses Junior's `github_createIssue` tool. Other issue operations use `gh` CLI and must be deterministic and non-interactive.
+Issue creation uses Junior's `github_createIssue` tool. Other issue operations use allowlisted REST endpoints through `gh api`; generic GraphQL-backed `gh issue` mutations are not supported.
 
 ## Repo scoping
 
@@ -10,22 +10,22 @@ Treat explicit repo flags as command-targeting safety rails, not as a credential
 
 ## GitHub App permission guidance
 
-| Permission capability | Operations                                                                                     |
-| --------------------- | ---------------------------------------------------------------------------------------------- |
-| `github.issues.read`  | `gh issue view`, `gh api /repos/.../comments`                                                  |
-| `github.issues.write` | `github_createIssue`, `gh issue edit`, `gh issue comment`, `gh issue close`, `gh issue reopen` |
+| Permission capability | Operations                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| `github.issues.read`  | `gh issue view`, `gh api /repos/.../comments`                                        |
+| `github.issues.write` | `github_createIssue` and allowlisted REST issue lifecycle endpoints through `gh api` |
 
 ## Command matrix
 
 | Operation           | Command                                                                                                       |
 | ------------------- | ------------------------------------------------------------------------------------------------------------- |
 | Create issue        | `github_createIssue({ repo: "owner/repo", title: "...", body: "...", labels: ["..."] })`                      |
-| Update issue fields | `gh issue edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]`                                   |
-| Close issue         | `gh issue close NUMBER --repo owner/repo [--comment "..."]`                                                   |
-| Reopen issue        | `gh issue reopen NUMBER --repo owner/repo`                                                                    |
-| Add labels          | `gh issue edit NUMBER --repo owner/repo --add-label LABEL [--add-label LABEL2]`                               |
-| Remove labels       | `gh issue edit NUMBER --repo owner/repo --remove-label LABEL [--remove-label LABEL2]`                         |
-| Add comment         | `gh issue comment NUMBER --repo owner/repo --body-file PATH`                                                  |
+| Update issue fields | `gh api repos/owner/repo/issues/NUMBER --method PATCH --input payload.json`                                   |
+| Close issue         | `gh api repos/owner/repo/issues/NUMBER --method PATCH -f state=closed`                                        |
+| Reopen issue        | `gh api repos/owner/repo/issues/NUMBER --method PATCH -f state=open`                                          |
+| Add labels          | `gh api repos/owner/repo/issues/NUMBER/labels --method POST --input labels.json`                              |
+| Remove label        | `gh api repos/owner/repo/issues/NUMBER/labels/LABEL --method DELETE`                                          |
+| Add comment         | `gh api repos/owner/repo/issues/NUMBER/comments --method POST --input comment.json`                           |
 | List issues         | `gh issue list --repo owner/repo --json number,title,state,url --limit 20`                                    |
 | Read issue          | `gh issue view NUMBER --repo owner/repo --json number,title,state,labels,assignees,author,url,body`           |
 | Read comments       | `gh api /repos/owner/repo/issues/NUMBER/comments --method GET --header "Accept: application/vnd.github+json"` |

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

@@ -9,15 +9,15 @@ Use this table to recover quickly while keeping operations deterministic.
 | 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 write request.               | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                        |
+| `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`.                                                         |
-| `gh issue edit` does not change labels                  | Wrong flag usage or wrong repo context.                                     | Use repeated `--add-label/--remove-label` flags and keep `--repo owner/repo` explicit.                                          |
-| Comment command fails with empty body                   | Body file missing/empty.                                                    | Ensure comment file exists and has content before `gh issue comment`.                                                           |
+| 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
 
 - Retry once for transient transport failures after verifying repo context.
 - Do not loop retries on repeated 401/403/404 validation errors.
-- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work; treat `installation-read` failures as app installation or host environment setup.
+- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work. Treat all `installation-*` failures as App permission, installation scope, or host environment setup; they do not fall back to user OAuth.
 - For persistent permission problems, return explicit remediation and stop.