@yemi33/minions 0.1.1950 → 0.1.1952

package/engine/gh-token.js

@@ -0,0 +1,137 @@
+/**
+ * engine/gh-token.js — Per-slug GitHub PAT resolution.
+ *
+ * Resolves the PAT for a given owner/repo slug by consulting
+ * `config.engine.ghAccounts` and shelling out to `gh auth token --user <account>
+ * --hostname github.com`. Threading the resolved token via `GH_TOKEN` lets
+ * `gh` calls hit the right account WITHOUT touching the global active account.
+ *
+ * Lookup chain for a slug `<owner>/<repo>`:
+ *   1. `engine.ghAccounts[<owner>]` — exact owner match.
+ *   2. `engine.ghAccounts[<owner>/* ]` — owner glob (optional).
+ *   3. `engine.ghAccounts['*']` — fleet default.
+ *   4. null → caller falls back to the ambient `gh` identity, preserving
+ *      legacy behavior for unmapped slugs.
+ *
+ * Mirrors the shape of `engine/ado-token.js` (separate sync token acquisition
+ * helper, in-memory cache, narrow exec timeout). Tests can prime the cache
+ * via `_setTokenForTest(slug, token)` and clear it via `_clearTokenCache()`.
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const shared = require('./shared');
+const { safeJson, MINIONS_DIR, log } = shared;
+
+const TOKEN_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const FETCH_TIMEOUT_MS = 10000;       // 10s — same ceiling as `gh api user`
+const MAX_BUFFER = 1024 * 1024;       // 1 MB — token output is ~80 chars
+const CONFIG_CACHE_MS = 30 * 1000;    // 30s — re-read config periodically without hammering fs
+
+const _accountTokens = new Map(); // accountName → { token, expiresAt }
+const _slugTokenOverrides = new Map(); // slug → token (test seam)
+
+let _cachedConfig = null;
+let _cachedConfigAt = 0;
+
+function _readConfig(opts = {}) {
+  if (opts.config) return opts.config;
+  if (_cachedConfig && (Date.now() - _cachedConfigAt) < CONFIG_CACHE_MS) {
+    return _cachedConfig;
+  }
+  const configPath = path.join(MINIONS_DIR, 'config.json');
+  _cachedConfig = safeJson(configPath) || {};
+  _cachedConfigAt = Date.now();
+  return _cachedConfig;
+}
+
+/**
+ * Resolve the configured gh account name for a slug, or null when no mapping
+ * applies. Mapping precedence: exact owner > owner-glob > fleet default ('*').
+ */
+function resolveAccountForSlug(slug, opts = {}) {
+  if (!slug || typeof slug !== 'string') return null;
+  const owner = slug.split('/')[0];
+  if (!owner) return null;
+
+  const config = _readConfig(opts);
+  const accounts = (config && config.engine && config.engine.ghAccounts) || {};
+  if (!accounts || typeof accounts !== 'object') return null;
+
+  if (accounts[owner]) return String(accounts[owner]);
+  const glob = `${owner}/*`;
+  if (accounts[glob]) return String(accounts[glob]);
+  if (accounts['*']) return String(accounts['*']);
+  return null;
+}
+
+function _fetchTokenForAccount(account, opts = {}) {
+  if (!account) return null;
+  const cached = _accountTokens.get(account);
+  if (cached && cached.expiresAt > Date.now()) return cached.token;
+
+  const run = opts.execSync || execSync;
+  try {
+    // Argv form via `gh` is safer than constructing a shell string when account
+    // names ever include odd chars; using execSync's command form here for
+    // consistency with ado-token.js, but the account name flows from a config
+    // map under our control (validated at write time).
+    const cmd = `gh auth token --user ${account} --hostname github.com`;
+    const out = run(cmd, {
+      timeout: FETCH_TIMEOUT_MS,
+      encoding: 'utf8',
+      windowsHide: true,
+      maxBuffer: MAX_BUFFER,
+    });
+    const token = String(out || '').trim();
+    if (!token) {
+      log('warn', `gh-token: empty token returned for account "${account}"`);
+      return null;
+    }
+    _accountTokens.set(account, { token, expiresAt: Date.now() + TOKEN_TTL_MS });
+    return token;
+  } catch (e) {
+    log('warn', `gh-token: failed to fetch token for "${account}": ${e?.message || e}`);
+    return null;
+  }
+}
+
+/**
+ * Resolve a GitHub PAT for `slug` (e.g. `opg-microsoft/minions`).
+ * Returns the token string on success, or null when no mapping applies and the
+ * caller should fall back to the ambient `gh` identity.
+ *
+ * Test seam: `_setTokenForTest(slug, token)` short-circuits the entire chain
+ * so unit tests do not have to mock execSync nor stand up a config file.
+ */
+function resolveTokenForSlug(slug, opts = {}) {
+  if (slug && _slugTokenOverrides.has(slug)) return _slugTokenOverrides.get(slug);
+  const account = resolveAccountForSlug(slug, opts);
+  if (!account) return null;
+  return _fetchTokenForAccount(account, opts);
+}
+
+/** Test-only: prime a slug→token override that bypasses config + shell-out. */
+function _setTokenForTest(slug, token) {
+  if (!slug) return;
+  if (token == null) _slugTokenOverrides.delete(slug);
+  else _slugTokenOverrides.set(slug, String(token));
+}
+
+/** Test-only: drop every cache so the next resolve goes through the real path. */
+function _clearTokenCache() {
+  _accountTokens.clear();
+  _slugTokenOverrides.clear();
+  _cachedConfig = null;
+  _cachedConfigAt = 0;
+}
+
+module.exports = {
+  resolveTokenForSlug,
+  resolveAccountForSlug,
+  _setTokenForTest,
+  _clearTokenCache,
+  // Constants exposed for tests + diagnostics.
+  TOKEN_TTL_MS,
+  FETCH_TIMEOUT_MS,
+};

package/engine/github.js

@@ -8,6 +8,7 @@ const shared = require('./shared');
 const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeJsonArr, safeWrite, mutateJsonFileLocked, mutatePullRequests, MINIONS_DIR, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, ENGINE_DEFAULTS, createThrottleTracker, getProjectOrg } = shared;
 const { getPrs } = require('./queries');
 const { MINIONS_COMMENT_MARKER_RE } = require('./gh-comment');
+const ghToken = require('./gh-token');
 const path = require('path');
 
 // Lazy require to avoid circular dependency — only needed for engine().handlePostMerge
@@ -149,29 +150,46 @@ function _isMinionsAuthoredComment(c) {
 // `pollPrHumanComments` (REST returns `viewerDidAuthor: null`). To make the
 // classifier alive in production without changing every fetch site to
 // GraphQL, we backfill the field by comparing the comment author's login to
-// the viewer login resolved via `gh api user` once per process. The shared
-// PAT identity does not change during a process lifetime, so a simple
-// in-memory cache is sufficient.
-let _cachedViewerLogin = null;
+// the viewer login resolved via `gh api user`.
+//
+// W-mp76pw7a001da7c1 — The viewer login is no longer process-wide because
+// `ghApi` now resolves a per-slug token via `engine/gh-token.js`. Different
+// accounts return different logins from `gh api user`, so the cache is keyed
+// by the resolved account name (or the sentinel `__ambient__` when no
+// account mapping applies and the call falls back to the ambient gh
+// identity). One shell-out per distinct account per process is still cheap.
+const _viewerLoginByAccount = new Map();
+const _AMBIENT_ACCOUNT = '__ambient__';
+
+function _accountKeyForSlug(slug) {
+  return ghToken.resolveAccountForSlug(slug) || _AMBIENT_ACCOUNT;
+}
 
-async function _resolveViewerLogin() {
-  if (_cachedViewerLogin) return _cachedViewerLogin;
+async function _resolveViewerLogin(slug) {
+  const account = _accountKeyForSlug(slug);
+  if (_viewerLoginByAccount.has(account)) return _viewerLoginByAccount.get(account);
   try {
-    const result = await _runExec('gh api user', { timeout: 10000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER });
+    const token = ghToken.resolveTokenForSlug(slug);
+    const env = token ? { ...process.env, GH_TOKEN: token } : process.env;
+    const result = await _runExec('gh api user', { timeout: 10000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER, env });
     const parsed = JSON.parse(String(result || ''));
     const login = parsed?.login ? String(parsed.login).toLowerCase() : null;
-    if (login) _cachedViewerLogin = login;
+    if (login) _viewerLoginByAccount.set(account, login);
     return login;
   } catch (e) {
-    log('warn', `GitHub viewer-login resolution failed: ${e?.message || e}`);
+    log('warn', `GitHub viewer-login resolution failed for ${slug || '<no-slug>'}: ${e?.message || e}`);
     return null;
   }
 }
 
-// Test hook: lets tests prime or clear the cached viewer login without
-// shelling out. Pass `null` to force a re-resolve on the next call.
-function _setCachedViewerLogin(login) {
-  _cachedViewerLogin = login ? String(login).toLowerCase() : null;
+// Test hook: lets tests prime or clear a cached viewer login per account
+// without shelling out. Pass `(account, null)` to force a re-resolve.
+// W-mp76pw7a001da7c1: signature changed from `(login)` → `(account, login)`
+// because the cache is now keyed by the resolved gh account name.
+function _setCachedViewerLogin(account, login) {
+  const key = account ? String(account) : _AMBIENT_ACCOUNT;
+  if (login == null) _viewerLoginByAccount.delete(key);
+  else _viewerLoginByAccount.set(key, String(login).toLowerCase());
 }
 
 // Backfill `c.viewerDidAuthor` for an array of REST-fetched comments using
@@ -254,7 +272,9 @@ async function ghApi(endpoint, slug, opts = {}) {
   try {
     const paginateFlag = opts.paginate ? ' --paginate' : '';
     const cmd = `gh api${paginateFlag} "repos/${slug}${endpoint}"`;
-    const result = await _runExec(cmd, { timeout: opts.timeout || 30000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER });
+    const token = ghToken.resolveTokenForSlug(slug);
+    const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
+    const result = await _runExec(cmd, { timeout: opts.timeout || 30000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER, env });
     const parsed = JSON.parse(result);
     _ghThrottle.recordSuccess();
     return parsed;
@@ -323,7 +343,9 @@ async function fetchGhBuildErrorLog(slug, failedRuns) {
       // Always fetch job log — annotations alone often lack test failure details
       try {
         const cmd = `gh api "repos/${slug}/actions/jobs/${run.id}/logs" 2>&1`;
-        const result = await _runExec(cmd, { timeout: 15000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER });
+        const token = ghToken.resolveTokenForSlug(slug);
+        const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
+        const result = await _runExec(cmd, { timeout: 15000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER, env });
         if (result && !result.includes('Not Found')) {
           logParts.push(`--- ${run.name || 'Check'} (log) ---\n${result}`);
         }
@@ -353,6 +375,15 @@ async function forEachActiveGhPr(config, callback) {
   let totalUpdated = 0;
 
   for (const project of projects) {
+    // W-mp625n27000m6e78 — Honor per-project workSources.pullRequests.enabled.
+    // Default-ON: only skip when explicitly disabled (=== false). Missing/undefined
+    // falls through to global workSources, then defaults to polling. Without this
+    // gate, disabling PR polling via the dashboard Settings UI was cosmetic — the
+    // engine still polled and could flip PRs to abandoned via the GH_NOT_FOUND
+    // trapdoor in pollPrStatus.
+    const src = project?.workSources?.pullRequests || config?.workSources?.pullRequests;
+    if (src && src.enabled === false) continue;
+
     const slug = getRepoSlug(project);
     if (!slug) continue;
 
@@ -490,9 +521,16 @@ async function forEachActiveGhPr(config, callback) {
             if (pr.description === undefined) pr.description = (prData.body || '').slice(0, 500);
             if (pr.agent === 'human' && prData.user?.login) pr.agent = prData.user.login;
             if (!pr.branch && prData.head?.ref) {
-              pr.branch = prData.head.ref;
-              if (pr._branchResolutionError) delete pr._branchResolutionError;
-              if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
+              // P-a7c4d2e8 (F3): validate API-derived branch ref before
+              // persistence. Defensive degrade — log and skip on invalid ref
+              // rather than crash the poller.
+              try {
+                pr.branch = shared.validateGitRef(prData.head.ref);
+                if (pr._branchResolutionError) delete pr._branchResolutionError;
+                if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
+              } catch (refErr) {
+                log('warn', `GitHub: invalid head.ref for PR ${pr.id}, skipping branch persistence: ${refErr.message}`);
+              }
             }
           }
         }
@@ -572,10 +610,16 @@ async function pollPrStatus(config) {
 
     const headBranch = prData.head?.ref ? String(prData.head.ref).trim() : '';
     if (headBranch && pr.branch !== headBranch) {
-      pr.branch = headBranch;
-      if (pr._branchResolutionError) delete pr._branchResolutionError;
-      if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
-      updated = true;
+      // P-a7c4d2e8 (F3): validate API-derived branch ref before persistence.
+      try {
+        const validated = shared.validateGitRef(headBranch);
+        pr.branch = validated;
+        if (pr._branchResolutionError) delete pr._branchResolutionError;
+        if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
+        updated = true;
+      } catch (refErr) {
+        log('warn', `GitHub: invalid head.ref "${headBranch.slice(0, 64)}" for PR ${pr.id}, skipping branch persistence: ${refErr.message}`);
+      }
     }
 
     // Map GitHub PR state to minions status
@@ -832,7 +876,8 @@ async function pollPrStatus(config) {
       if (autoComplete) {
         try {
           const mergeMethod = ['squash', 'merge', 'rebase'].includes(config.engine?.prMergeMethod) ? config.engine.prMergeMethod : 'squash';
-          await _runExec(`gh pr merge ${prNum} --${mergeMethod} --repo ${slug} --delete-branch`, { timeout: 30000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER });
+          // P-a7c4d2e8 (F1): argv-form merge call — eliminates shell interpolation of slug/prNum/mergeMethod.
+          await shared.shellSafeGh(['pr', 'merge', String(prNum), `--${mergeMethod}`, '--repo', shared.validateGhSlug(slug), '--delete-branch'], { timeout: 30000, maxBuffer: GH_MAX_BUFFER });
           pr._autoCompleted = true;
           log('info', `Auto-completed PR ${pr.id}: builds green + review approved → merged (${mergeMethod})`);
           updated = true;
@@ -861,12 +906,12 @@ async function pollPrHumanComments(config) {
     try { return queries.getDispatch(); }
     catch { return { pending: [], active: [], completed: [] }; }
   })();
-  // Resolve viewer login once per poll cycle so we can backfill
-  // `viewerDidAuthor` on REST comments — the field GraphQL would have
-  // populated. `_resolveViewerLogin` caches process-wide, so repeated calls
-  // across PRs are free.
-  const viewerLogin = await _resolveViewerLogin();
+  // Viewer login is resolved per-PR (cheap on cache hit) because each slug
+  // can route to a different gh account via `engine/gh-token.js`. The cache
+  // is keyed by the resolved account name, so multiple PRs sharing one
+  // account pay only the first shell-out.
   const totalUpdated = await forEachActiveGhPr(config, async (project, pr, prNum, slug) => {
+    const viewerLogin = await _resolveViewerLogin(slug);
     // Get issue comments (general PR comments)
     const comments = await ghApi(`/issues/${prNum}/comments`, slug);
     if (!comments || !Array.isArray(comments)) return false;
@@ -1012,7 +1057,17 @@ async function reconcilePrs(config) {
     for (const ghPr of ghPrs) {
       const prUrl = project.prUrlBase ? project.prUrlBase + ghPr.number : ghPr.html_url || '';
       const prId = shared.getCanonicalPrId(project, ghPr.number, prUrl);
-      const branch = ghPr.head?.ref || '';
+      // P-a7c4d2e8 (F3): validate API-derived branch ref before persistence
+      // / regex matching. Defensive degrade — log and treat as missing on
+      // invalid ref rather than letting it flow into stored records.
+      const rawBranch = ghPr.head?.ref || '';
+      let branch = '';
+      if (rawBranch) {
+        try { branch = shared.validateGitRef(rawBranch); }
+        catch (refErr) {
+          log('warn', `GitHub: invalid head.ref "${rawBranch.slice(0, 64)}" for PR ${prId}: ${refErr.message}`);
+        }
+      }
       const wiMatch = branch.match(/(P-[a-z0-9]{6,})/i) || branch.match(/(W-[a-z0-9]{6,})/i) || branch.match(/(PL-[a-z0-9]{6,})/i);
       const linkedItemId = wiMatch ? wiMatch[1] : null;
       const linkedItem = linkedItemId ? allItems.find(i => i.id === linkedItemId) : null;
@@ -1134,6 +1189,85 @@ async function checkLiveReviewStatus(pr, project) {
   }
 }
 
+/**
+ * W-mp7b1g8q000fea45 — Dismiss prior CHANGES_REQUESTED reviews by the
+ * authenticated viewer when an agent flips their verdict to approved.
+ *
+ * GitHub doesn't auto-supersede prior reviews: a new COMMENTED review (which is
+ * what minions agents post on GH per CLAUDE.md "GitHub review self-approval
+ * constraint") leaves any earlier `CHANGES_REQUESTED` review by the same login
+ * intact, so `checkLiveReviewStatus` still returns 'changes-requested' and the
+ * red ❌ badge stays on the PR. Active dismissal via PUT
+ * /repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/dismissals
+ * clears the stale red badge.
+ *
+ * Only dismisses reviews whose state is CHANGES_REQUESTED AND whose author
+ * matches the resolved viewer login (i.e., the engine's own gh PAT). Human
+ * CHANGES_REQUESTED reviews under a different login are never touched.
+ *
+ * Returns null on transport failure. Otherwise returns
+ *   { attempted: boolean, dismissed: number, errors: number }
+ */
+async function dismissPriorViewerChangesRequestedReviews(pr, project) {
+  let tmpFile = null;
+  try {
+    const slug = getRepoSlug(project);
+    if (!slug) return null;
+    const prNum = shared.getPrNumber(pr);
+    if (!prNum) return null;
+    const viewerLogin = await _resolveViewerLogin(slug);
+    if (!viewerLogin) return null;
+    const reviews = await ghApi(`/pulls/${prNum}/reviews`, slug);
+    if (!reviews || !Array.isArray(reviews)) return null;
+    // Latest CHANGES_REQUESTED review IDs by the viewer login. The reviews API
+    // returns them in chronological order; we keep all that are still active
+    // (not already dismissed) since GitHub's per-user "latest" semantics are
+    // computed from non-dismissed reviews and we want the badge fully cleared.
+    const viewerLower = String(viewerLogin).toLowerCase();
+    const targets = reviews
+      .filter(r => r && r.state === 'CHANGES_REQUESTED' && String(r.user?.login || '').toLowerCase() === viewerLower)
+      .map(r => r.id)
+      .filter(Number.isFinite);
+    if (targets.length === 0) {
+      return { attempted: false, dismissed: 0, errors: 0 };
+    }
+    const fs = require('fs');
+    const os = require('os');
+    let dismissed = 0;
+    let errors = 0;
+    for (const reviewId of targets) {
+      tmpFile = path.join(os.tmpdir(), `gh-review-dismiss-${process.pid}-${Date.now()}-${reviewId}.json`);
+      const body = JSON.stringify({
+        message: 'Superseded by Minions re-review (verdict flipped to APPROVE).',
+        event: 'DISMISS',
+      });
+      try {
+        fs.writeFileSync(tmpFile, body);
+        const cmd = `gh api -X PUT --input "${tmpFile}" "repos/${slug}/pulls/${prNum}/reviews/${reviewId}/dismissals"`;
+        const token = ghToken.resolveTokenForSlug(slug);
+        const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
+        await _runExec(cmd, { timeout: 10000, encoding: 'utf-8', maxBuffer: GH_MAX_BUFFER, env });
+        dismissed += 1;
+        log('info', `PR ${pr.id}: dismissed prior CHANGES_REQUESTED review ${reviewId} by ${viewerLogin}`);
+      } catch (e) {
+        errors += 1;
+        log('warn', `PR ${pr.id}: dismiss review ${reviewId} failed: ${e?.message || e}`);
+      } finally {
+        try { fs.unlinkSync(tmpFile); } catch {}
+        tmpFile = null;
+      }
+    }
+    return { attempted: true, dismissed, errors };
+  } catch (e) {
+    log('warn', `dismissPriorViewerChangesRequestedReviews for ${pr?.id || 'unknown PR'}: ${e?.message || e}`);
+    return null;
+  } finally {
+    if (tmpFile) {
+      try { require('fs').unlinkSync(tmpFile); } catch {}
+    }
+  }
+}
+
 /**
  * Cheap pre-dispatch freshness check for build status and merge-conflict state.
  * Mirrors checkLiveReviewStatus — fetches PR data once, classifies check-runs
@@ -1356,6 +1490,7 @@ module.exports = {
   reconcileAbandonedPrs, // W-mp60tw0u000j3931 — one-shot startup re-probe of abandoned PRs
   checkLiveReviewStatus,
   checkLiveBuildAndConflict,
+  dismissPriorViewerChangesRequestedReviews, // W-mp7b1g8q000fea45 — clear stale CHANGES_REQUESTED on verdict flip
   isGhThrottled,
   getGhThrottleState,
   // Exported for testing
@@ -1369,6 +1504,8 @@ module.exports = {
   GH_MAX_BUFFER, // exported for testing
   GH_POLL_BACKOFF_BASE_MS, // exported for testing
   GH_POLL_BACKOFF_MAX_MS, // exported for testing
+  GH_NOT_FOUND, // W-mp625n27000m6e78 — exported for forEachActiveGhPr probe-predicate tests
+  forEachActiveGhPr, // W-mp625n27000m6e78 — exported for workSources-gate + probe tests
   _hasMinionsReviewVerdict, // exported for testing
   _isAgentComment, // exported for testing
   _isNonActionableComment, // exported for testing

package/engine/issues.js

@@ -6,6 +6,7 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync: _execFileSync } = require('child_process');
 const shared = require('./shared');
+const ghToken = require('./gh-token');
 
 const DEFAULT_REPO = 'yemi33/minions';
 const DEFAULT_LABELS = ['bug'];
@@ -113,6 +114,34 @@ function ghTokenForUser({ user, execFileSync }) {
 }
 
 function resolveWritableGitHubEnv({ repo, execFileSync }) {
+  // W-mp76pw7a001da7c1 — Try the per-slug resolver FIRST. If `engine.ghAccounts`
+  // maps this owner to a specific gh account, use that account's token instead
+  // of probing whatever account is globally active. Falls through to the
+  // legacy active-account / enumerate-all-accounts path when the resolver
+  // returns null (preserves backward compat for unmapped slugs).
+  try {
+    const mappedToken = ghToken.resolveTokenForSlug(repo);
+    if (mappedToken) {
+      const ghEnv = { GH_TOKEN: mappedToken };
+      try {
+        const permission = repoViewerPermission({ repo, execFileSync, ghEnv });
+        if (isWritableRepoPermission(permission)) return ghEnv;
+      } catch { /* fall through to legacy enumeration */ }
+    }
+  } catch { /* fall through to legacy enumeration */ }
+
+  // Final fallback: explicit GH_TOKEN env var. Only consulted when no mapping
+  // produced a usable token. Honors the contract spelled out in the task —
+  // resolver is primary, GH_TOKEN env is the env-side fallback.
+  const envToken = String(process.env.GH_TOKEN || '').trim();
+  if (envToken) {
+    const ghEnv = { GH_TOKEN: envToken };
+    try {
+      const permission = repoViewerPermission({ repo, execFileSync, ghEnv });
+      if (isWritableRepoPermission(permission)) return ghEnv;
+    } catch { /* fall through */ }
+  }
+
   let activePermission = '';
   let activeError = null;
   try {