takeover mode: agents cannot auto-open PRs — GitHub App missing pull_requests / actions / secrets permissions

[nicgzlfly]

Problem

When running wanman takeover against a GitHub-hosted repo, agents (dev, cto) follow the documented git workflow:

feature branch → write code → push → gh pr create → notify CTO

However, the gh pr create call fails (or silently skips) because the GitHub App / installation token that wanman provisions does not include the required scopes/permissions.

Observed in: takeover of nicgzlfly/-_the-crowd (2026-04-30)

---

Missing permissions

Permission	Needed for	Observed state
pull_requests: write	gh pr create — agents opening PRs	❌ missing
actions: write (or read)	Agents reading CI run status via gh run list / triggering re-runs	❌ missing
secrets: read	Workflows that reference ${{ secrets.* }} (deploy pipeline uses SSH_PRIVATE_KEY, SERVER_HOST, etc.)	❌ not accessible to App token

---

Reproduction

1. Install wanman and run wanman takeover /path/to/repo against a private GitHub repo.
2. Assign a dev task with a feature branch target.
3. Dev agent pushes branch and calls gh pr create.
4. PR creation fails or is skipped because the GitHub App installation token lacks pull_requests: write.

---

Expected behavior

• wanman takeover setup flow (or docs) should verify that the configured GitHub App installation has at minimum:
  • pull_requests: write
  • actions: read (so agents can poll CI status)
  • contents: write (branch push)
• If permissions are insufficient, wanman should surface a clear error at startup rather than silently failing mid-task.

Suggested fix / detection

Add a pre-flight check in takeover-local.ts (or takeover-project.ts) that calls:

gh api repos/{owner}/{repo}/actions/permissions
gh api repos/{owner}/{repo} --jq '.permissions'

...and warns the user if pull_requests permission is absent before agents start working.

Alternatively, document the exact GitHub App permission set that must be granted before running wanman takeover.

---

Environment

• wanman CLI built from local source (packages/cli/dist/index.js)
• Runtime: claude (Claude Code subprocess)
• Repo type: GitHub public/private
• Auth: personal gh token with repo, workflow scopes (agents inherit this; App token is separate)

---

References

• packages/cli/src/takeover-project.ts lines 773–787 (CTO PR review workflow)
• packages/cli/src/takeover-local.ts detectPullRequestUrl() (assumes PR already exists)
• Skill doc: wanman/<task-slug> branch → gh pr create documented as required dev step

cc @chekusu

[guo-yu]

I checked the current takeover code and agree that this is still a real preflight/docs gap.

Code evidence:

• The generated dev workflow in packages/cli/src/takeover-project.ts explicitly tells agents to git push -u origin wanman/<task-slug> and then run gh pr create.
• The CTO workflow in the same file expects gh pr checks, gh pr review, and gh pr merge to work.
• packages/cli/src/takeover-local.ts has detectPullRequestUrl(), but it only runs gh pr list --head ... and returns undefined on any error. It does not distinguish “no PR yet” from “GitHub auth/token cannot read PRs”.
• I did not find a startup preflight that verifies PR/action permissions before the agents begin work.

One caveat: gh api repos/{owner}/{repo} --jq '.permissions' verifies the active gh token’s repo role, but it does not necessarily prove that a separate GitHub App installation token has pull_requests: write or actions: read. If takeover can run under either a user token or an app token, the check should be tied to the exact credential that agents will inherit.

Suggested acceptance for a fix:

• During wanman takeover startup, detect the Git remote owner/repo.
• Run a credential preflight for the actual token exposed to agents:
  • can read repo metadata
  • can push a branch or at least has contents write capability when that mode is expected
  • can create/read PRs
  • can read Actions runs if the generated workflow tells CTO to use gh pr checks / gh run list
• If any check fails, fail early with a concrete remediation message instead of letting the dev/CTO agents discover it mid-task.
• Update the takeover docs with the minimum required GitHub permissions for both user-token and GitHub-App-token modes.

So I would keep this open. The fix is probably a preflight + docs change rather than only changing the prompt.