security: give agent sessions their own GitHub App identity before unattended merge #7711

Parent

Refs #7570 (thread: Merge authority and verifier), #7709 item 10 (decided by the owner on 2026-10-17: agent sessions get their own GitHub identity before report-only flips). Research: .work/poteto-review/design/agent-identity-research.md in the owner's checkout; GitHub docs fetched 2026-10-17.

Problem

The verifier's trusted-spec check and the admission marker rule (D33) trust any issue or comment from an account on trusted-actors.json. Agent sessions run gh with the owner's login (an OAuth gho_ token), so whatever they post reads as the owner's. The marker check (ratification.mjs) accepts a comment from a listed human, not posted through an App, and never edited. An agent posting as the owner passes all three tests. A trusted account therefore proves the account, not that a person wrote or reviewed the text.

Proposal

Agent sessions act as a GitHub App of their own, separate from the lanes App, using one-hour installation tokens minted per session. Reuse the dormant melodic-ai App: it has received zero events, its key is already in the estate's GitHub key vault, and dotfiles user-env.yaml:30 lists it with no local consumer. kyle-sexton stays the only kind: human trusted actor. The App is listed only as kind: bot, and only where a trigger has to accept it.

Why an App, not a machine user:

• Two gates decide "human" by account type: babysit's is_human (babysit_merge_policy.py:735-760) and the pr-merge labeler rule (pr-pipeline/README.md:432-435). A machine user is a User and would pass both as human. An App is a Bot and already fails both.
• A machine user needs an org seat, because an outside collaborator cannot use a fine-grained PAT. The org's one seat is filled. Apps take no seat, and GitHub's PAT docs point organization automation to Apps.
• GitHub's Terms allow one free machine account per person, created by that person, who is responsible for what it does.

What it closes beyond the spec check:

• Sessions can no longer post a valid admission marker. That is intended, and the code needs no change.
• github-iac ADR 0015 accepted risk 2: the App holds no org-admin role, so a session cannot merge with --admin.

Owner decisions

1. App: reuse melodic-ai (recommended) or register a new one. Either way: no administration permission, installed on selected repositories with azure-iac excluded (ADR 0015 trigger 5: there it could mint lane tokens), a new key generated and the old one retired.
2. Token isolation: without it, an agent can unset GH_TOKEN and act as the owner again, so the App changes the credit, not the reach. Recommended: unattended lanes run as a separate OS user that cannot read the owner's token. Interactive sessions get a separate GH_CONFIG_DIR, plus a guardrails rule that denies gh auth switches and unsetting GH_TOKEN. Basis: judgment, since interactive sessions have the owner present.
3. Key handling: sign the App JWT inside the vault, the azure-iac broker pattern, so the key never reaches a host (recommended). The alternative is vault-exec, which hands the key to the host process. Basis: GitHub's App key guidance, and the existing broker pattern.
4. Merge-lane eligibility: PRs from agent sessions stay out of unattended merge (not-lane-authored is unchanged); recommended. The lanes App remains the only unattended author.
5. Required review for agent PRs: github-iac ADR 0007 revisit trigger 3 fires, because an owner approval becomes a real second review. Recommended: record it and defer. The verifier is the gate for lane PRs.

Agent-doable work, as draft PRs after the decisions

• dotfiles: a token mint helper and session launcher (bash and PowerShell) that set GH_TOKEN, GH_CONFIG_DIR and the git author.
• claude-code-plugins: the App login in babysit's self_logins default; a guardrails rule against identity switches; ratification tests proving an App-posted marker is refused.
• architecture: a trust-link entry and an ADR; amendments to github-iac ADR 0015 and ADR 0007.
• Post-cutover probes: a session's issue reads as the App, and its marker does not admit.
• Not yet checked: commit signing on requires-signing repos, and the commit author format.

Done when

• The owner settles decisions 1-5.
• An interactive and an unattended session each post an issue that reads as the App, and neither can act as the owner (probe recorded).
• An App-posted admission marker does not admit (test plus live probe).
• source-control: settle the verifier verdict follow-ups before report-only flips #7709 item 10 is closed with a pointer here.