feat(agent): write-permission readiness gate (#775)

[JSONbored]

Closes #775

What & why

Phase 0 of the agent layer (#768) is deny-by-default trust scaffolding. Before the action layer (#778) can mutate a real PR, it must know whether the App even holds the scope to do so — and if not, surface that the maintainer needs to re-consent. This adds that readiness gate as two pure helpers in src/settings/agent-execution.ts, alongside the kill-switch/dry-run mode resolver from #776.

The gate

• agentRequiresPrWrite(autonomy) — true when any acting autonomy level (auto / auto_with_approval) is configured for a PR-write action class (review / request_changes / approve / merge / close). label is intentionally excluded: it mutates via the Issues API, which the App already holds issues: write for, so it never demands pull_requests: write.
• resolveAgentPermissionReadiness({ autonomy, installationPermissions }) →
  • not_required — no acting PR-write level configured, so the scope is irrelevant
  • ready — the installation grants pull_requests: write
  • reconsent_required — an acting PR-write level is configured but the App only holds read (or the scope is missing): the maintainer must re-authorize with the upgraded permission

Both are pure and deny-toward-safety, mirroring resolveAgentActionMode (#776). #778 consults resolveAgentPermissionReadiness before executing any PR-write action.

Scope boundary (follow-ups, not in this PR)

• The actual GitHub App pull_requests: write permission upgrade + the maintainer re-consent prompt UI are install-side ops. The App owner has approved requesting the upgraded scope; wiring the re-consent surface lands with the action layer (feat(agent): maintainer write-actions layer (request-changes/approve/merge/close/label) #778) that consumes this gate.

Tests

test/unit/agent-execution.test.ts — new agent write-permission readiness (#775) block covering both helpers across acting/non-acting levels, the label exclusion, and ready / reconsent_required / not_required for write / read / missing / null granted scopes. Full suite green (2023 passed); agent-execution.ts at 100% statements + branches.

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#843 is no longer open.	No action.

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

[ghost]

gittensory · advisory review

Reviewed 2 changed file(s) — two independent AI reviewers.

Changed files: src/settings/agent-execution.ts, test/unit/agent-execution.test.ts

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
The PR introduces a permission‑readiness gate for PR‑write actions, adding utility functions and corresponding unit tests. The implementation is straightforward, type‑safe, and respects existing permission handling.

Suggestions

• Consider adding a test case for unexpected permission values (e.g., "admin") to ensure the function defaults to "reconsent_required".
• Update any module barrel exports if you want these new functions publicly available beyond this file.

Worth double-checking

• If other parts of the codebase start relying on resolveAgentPermissionReadiness, ensure they handle the "reconsent_required" case appropriately.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds a write-permission readiness gate for agent actions that mutate PR state (review, request_changes, approve, merge, close). It introduces two pure functions: agentRequiresPrWrite to detect if any PR-write action class has an acting autonomy level, and resolveAgentPermissionReadiness to determine if the installation has the required pull_requests: write scope. The changes are well-tested with unit tests covering all logic branches and edge cases. No public-facing output or forbidden terms are introduced, maintaining the public/private boundary.

Worth double-checking

• Ensure the imported resolveAutonomy and isActingAutonomyLevel from './autonomy' function correctly (not modified in this PR).
• Verify that the PR_WRITE_ACTION_CLASSES list aligns with GitHub's API requirements for write scope (currently correct).

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.59%. Comparing base (27a3ba6) to head (710b8aa).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #843   +/-   ##
=======================================
  Coverage   96.59%   96.59%           
=======================================
  Files         100      100           
  Lines       14240    14244    +4     
  Branches     5190     5192    +2     
=======================================
+ Hits        13755    13759    +4     
  Misses        105      105           
  Partials      380      380           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.