[P1][spec] Per-agent App identities (ADR-0030 Phase 2) — Friday shipping target

[aegis-gh-agent]

Summary

This is the implementation spec for the per-agent identity work that resolves the proxy-sign-off pattern structurally. It tracks Phase 2 of ADR-0030 — registering three per-agent GitHub Apps (aegis-hermes, aegis-argus, aegis-hephaestus) with scoped permissions per role.

Terminology note up front: the orchestrator's framing in #aegis-devs on 2026-06-10 was "per-agent PAT work" — but ADR-0030 explicitly rejected per-agent PATs as a security anti-pattern ("PATs in plaintext credentials are a P1 finding. Per-agent PATs scale the problem instead of fixing it. Per-agent Apps are the right primitive."). This spec implements the per-agent App path that ADR-0030 recommended. If anyone is specifically asking for the PAT path, please comment and we'll re-litigate; the decision is already on the record in the merged ADR.

This is a tracking/spec issue, not a PR. The work has 6 sub-tasks; each will land as its own PR with a 9-gate review.

Why this is P1

The proxy-sign-off pattern has been an active operational debt for 5 days and counting:

• 5 instances in 12h on 2026-06-10 (security: path traversal in dashboard-static.ts setHeaders (CodeQL path-injection) #4647, fix(security): drop manual statSync in dashboard-static setHeaders (#4647) #4653, fix(security): close TOCTOU race in secureFilePermissions via file descriptor (#4650 follow-up) #4656, etc.) — every App-authored PR needs Ema UI-approve, with the review body authored by OneStepAt4time because the bot can't self-approve. The audit trail attributes the review to Ema, not the actual reviewer.
• @Themis on GitHub is a real unrelated user (id 7315965, "John Snow") — the @-mention is a name collision, not a real security review attribution.
• One-time governance override granted for fix(security): inject redactError into TgApiConfig for token redaction (#4629) #4657 (Boss, 2026-06-10 09:57 GMT+2) — the override is one-shot. The next proxy sign-off will need another explicit override, or the work has to wait.
• Boss's call: ship this structural fix and retire the proxy-sign-off pattern. governance: codify proxy-sign-off rule for security reviews when per-agent PAT is unavailable #4658 (governance codification) is the interim rule until this lands.

Acceptance criteria

Phase 2 is done when all of the following are true:

A. Apps registered and installed

• aegis-hermes GitHub App registered (Ema action: https://github.com/settings/apps/new)

  • Display name: aegis-hermes (with [bot] suffix applied by GitHub)
  • Icon + homepage URL: per Hermes's signature (🏛 courier glyph, link to team roster)
  • Webhook: disabled (we don't need inbound webhooks; this is an outbound-only identity)

• aegis-argus GitHub App registered (same registration path)

• aegis-hephaestus GitHub App registered (same registration path)

• All 3 Apps installed on OneStepAt4time/aegis with the per-role permission matrix from ADR-0030 §"Phase 2":

  Agent	Repository contents	Workflows	Issues	Pull requests	Reviews	Releases
  aegis-hermes	write	write	write	write	—	write
  aegis-argus	read	—	read	read	write	—
  aegis-hephaestus	write	—	write	write	—	—

  (— means the App does not request that permission.)

B. Per-agent credentials on disk

• 3 new PEMs stored at ~/.openclaw/workspace/infra/github-apps/<app>.pem (mode 600, owner bubuntu:bubuntu — per the 2026-06-04 perm sweep pattern)
• 3 new sibling scripts: get-installation-token-hermes.sh, get-installation-token-argus.sh, get-installation-token-hephaestus.sh (mode 755, owner bubuntu:bubuntu), each returning 1h-TTL installation tokens for its App
• Each script independently tested: TOKEN=$(./get-installation-token-<role>.sh); GH_TOKEN=$TOKEN gh api /repos/OneStepAt4time/aegis -i | head -3 returns the repo metadata
• No PEMs leak into ~/.git-credentials or any other store; git credential-store list shows only the 3 pre-existing tokens (Ema's gho_, etc.)

C. Operability

• manage-aegis-apps.sh script written (ADR-0030 §Implementation Plan step 3). Enforces known-good permission matrix on registration; refuses to register an App with extra permissions not in the matrix.
• 90-day rotation reminder set (cron, per App). Initial 3 Apps inherit the rotation policy; new Apps added to the cron at registration time.
• Per-agent Discord identity (e.g., <@aegis-hermes>, <@aegis-argus>, <@aegis-hephaestus>) registered in AGENTS_TEAM_OPERATING_MODEL.md roster
• 3 new test fixtures in src/__tests__/auth/ (or equivalent) that exercise: token mint, token expiry, role-scope enforcement. Themis reviews the test plan.

D. Migration

• aegis-gh-agent (current bot) is marked as fallback identity in manage-aegis-apps.sh and HEARTBEAT
• 30-day parallel-run window: new work attributed to per-agent Apps; old work attributed to aegis-gh-agent. After 30 days, aegis-gh-agent App is uninstalled and removed.
• Ema's gho_ OAuth token in ~/.git-credentials is removed (per the ADR's "PAT cleanup" open question) only after the script recipe is confirmed canonical for all paths Hermes, Argus, Hephaestus use
• ADR-0031 filed: per-agent CODEOWNERS rules (which agents can self-approve which file globs). This is the separate ADR that ADR-0030 explicitly punted to a follow-up.

E. Audit / observability

• gh api /repos/OneStepAt4time/aegis/commits?author=<app-login> works for all 3 Apps (proves attribution is distinct)
• Per-agent rate-limit dashboard query returns separate counters (proves App-level rate-limit isolation)
• manage-aegis-apps.sh audit prints a status report: per-App install state, last rotation date, last use, drift from matrix
• HEARTBEAT.md updated with per-agent section (Hermes lane) referencing the canonical auth path

F. Governance

• governance: codify proxy-sign-off rule for security reviews when per-agent PAT is unavailable #4658 (proxy-sign-off governance codification) is closed as superseded once Phase 2 ships. The sunset clause fires.
• AGENTS_TEAM_OPERATING_MODEL.md §"Review" updated to reflect per-agent App identities (no more aegis-gh-agent[bot] IS Argus workaround framing)
• Any reference to "bot self-approval blocker" in the team's docs is removed or marked resolved

Scope

In scope

• 3 App registrations
• 3 PEMs + 3 token-mint scripts
• manage-aegis-apps.sh (registration, audit, rotation reminders)
• Per-agent Discord identities
• Per-agent test fixtures
• 30-day migration plan
• ADR-0031 (per-agent CODEOWNERS)

Out of scope (explicit)

• Workflows that branch on actor identity in a more granular way than App-level. The 3 Apps are the granularity unit; further splitting (e.g., one App per workstream) is a Phase 3 conversation. ADR-0030's permission matrix is the ceiling for Phase 2.
• Multi-org install. Phase 2 is single-org (OneStepAt4time). If/when Aegis mirrors to other orgs (e.g., for SOC2 audit partners), that's a separate migration.
• Renaming aegis-gh-agent to aegis-shared[bot]. Discussed but deferred — the legacy name stays for the 30-day migration; the App is uninstalled, not renamed.
• Removing the script recipe's pre-flight check for OAuth PAT. The script-mint path is canonical; the OAuth PAT in ~/.config/gh/hosts.yml remains as a fallback for emergency recovery. Removing it is a separate, later decision.

ETA — Friday shipping target

Target: ship by EOD Friday 2026-06-12 (Rome). 2 days from today (Wednesday 2026-06-10).

Working backward from Friday EOD:

Day	Time	Owner	Action
Wed 06-10	EOD	Ema	Approve scope. Register the 3 Apps. Send me the App IDs + PEMs.
Wed 06-10	EOD	Hermes	Receive PEMs, store at canonical paths, chmod 600. Smoke-test the 3 mint scripts.
Thu 06-11	AM	Hermes	Write manage-aegis-apps.sh. Test fixtures. Per-agent Discord identities.
Thu 06-11	AM	Hephaestus	(optional, in Hep's lane) Update workspace CI configs to use the new per-agent tokens if any local scripts reference aegis-gh-agent.
Thu 06-11	PM	Themis	Security review: PEM storage, scope matrix, 1h TTL mint, fallback path. Sign-off.
Thu 06-11	PM	Argus	Code review of manage-aegis-apps.sh + test fixtures. 9-gate review.
Thu 06-11	EOD	Hermes	Land the registration PR. Run a real push via the new App identity to verify attribution is distinct.
Fri 06-12	AM	Hermes	Update HEARTBEAT, OPERATIONAL-RULES.md, AGENTS_TEAM_OPERATING_MODEL.md. Close #4658. File ADR-0031.
Fri 06-12	PM	Boss + Ema	Confirm: structural fix shipped, proxy-sign-off pattern retired. Friday target met.

Dependencies (must clear for Friday to hold):

1. Ema registers 3 Apps by EOD Wed. Blocks everything downstream. (10 min of Ema's time per the ADR's estimate.)
2. PEMs are transferred via secure surface. Per Themis's standing rule: never paste in chat. Use gh auth login --web device-code flow, 1Password share, or scp to a known host. Channel-paste is OUT.
3. Themis has a 2h review window on Thu PM. The review is the same Themis security-review checklist that's already in ADR-0030 §"Security review checklist" — but applied to the new per-agent setups.
4. The OpenClaw P1 from yesterday (openclaw/openclaw#91827) does not block this. Different system, different repo, different reviewer chain. (Listed here only because Boss's message cited both in sequence.)

Risk: if any of the 4 dependencies slips, the realistic fallback is Mon 2026-06-15 (next sprint start). Friday is the target, not a hard deadline — I will signal in #aegis-devs the moment any dependency drifts.

Acceptance verification

When Ema asks "is it shipped?", the answer is "yes" iff:

1. gh check: gh api /repos/OneStepAt4time/aegis/installation returns 3 distinct installations (one per App), each with the per-role permission matrix from the ADR
2. attribution check: 1 commit pushed via aegis-hermes[bot]'s install token shows up in gh api /repos/OneStepAt4time/aegis/commits?author=aegis-hermes[bot] (proves App identity is wired, not just installed)
3. review check: an aegis-hephaestus[bot]-authored PR can be APPROVE'd by aegis-argus[bot] review, with the merge then proceeding on Ema's CODEOWNERS UI-approve (proves cross-App review works)
4. fallback check: aegis-gh-agent still works for emergency pushes; per-agent Apps are the canonical path
5. observability check: HEARTBEAT.md has a per-agent auth section; the manage-aegis-apps.sh audit command works; the 90-day rotation cron is armed

Related

• ADR-0030 (Agent Auth — Per-agent PAT vs Second GitHub App) — the decision document; Phase 2 is the spec
• docs(adr): 0030 — agent auth RFC (per-agent PAT vs second GitHub App) #4591 — the PR that landed ADR-0030 (closed)
• governance: codify proxy-sign-off rule for security reviews when per-agent PAT is unavailable #4658 — interim proxy-sign-off governance rule (this spec closes it on success)
• HEARTBEAT 2026-06-04 05:30Z — the gho_ OAuth token issue
• HEARTBEAT 2026-06-04 06:00Z — the script-recipe canonical auth path
• HEARTBEAT 2026-06-05 05:30Z — ci: helm-smoke fails with k3d install.sh 404 — AbsaOSS/k3d-action@v2 default download URL broken #4586 push-blocked-by-App-permissions (Gap 1; Phase 1 unblock)
• 2026-06-04 Themis perm sweep — credential file perms clean (mode 600, owner bubuntu:bubuntu)

Filing

Filed by: aegis-hermes[bot] (Hermes, Release/DevOps) per orchestrator directive 2026-06-10 15:13 GMT+2 in #aegis-devs. Priority P1 per the directive ("yesterday's P1 commitment").

Cross-references for the orchestrator:

• The OpenClaw P1 (kimi-code feedback loop) was filed yesterday as openclaw/openclaw#91827.
• This is the Aegis-side P1 (per-agent identity work) that Boss was nudging about.
• The two are decoupled — different repos, different fix paths, different reviewer chains.