Add read-only GitHub Issues access to agent enclaves

[lpcox]

Summary

• add the closed enclaves[].agent.github.cli: issues-read-v1 syntax to the user and AWF schemas
• generate the immutable mcpg enclave policy with inherited GitHub integrity, exact dotted Issues operations, repository sensitivities, and a deterministic run-bound proxy identity
• start and clean up a dedicated bridge-mode mcpg proxy, handing AWF only the container, identity, CA certificate, capability root key, and masked host-only gateway key
• request a TLS certificate SAN for the fixed private-network alias awf-enclave-github-proxy
• exclude trusted handoff values from the primary agent and clear the root key after AWF execution
• document supported REST routes, repository-scoped DIFC behavior, isolation guarantees, and dependency minimums

Smoke-run fixes

Smoke run 32928731346 exposed an ordering bug: the compiler's eager Start MCP Gateway functionality check treated the AWF-owned awf-enclave backend like an already-running required server. This PR classifies only the compiler-owned exact server name awf-enclave as deferred for that eager check. It remains required in mcpg configuration, the authenticated route remains fail-closed, arbitrary/user-selected names cannot be deferred, ordinary required failures remain fatal, and AWF still owns bounded initialize plus tools/list readiness after attachment.

Smoke run 32998355218 then showed the masked MCP_GATEWAY_API_KEY was unavailable to the host AWF process. GitHub Actions may suppress secret-valued step outputs after ::add-mask::, so enclave workflows now carry the already-masked key through the existing compiler-owned GITHUB_ENV host handoff. Enclave mount, execution, and cleanup steps inherit it instead of overriding it with the suppressed output. AWF still receives --exclude-env MCP_GATEWAY_API_KEY, so the primary agent cannot read the key, and the value is never placed in agent configuration or logs.

Smoke run 33004295192 proved the key handoff and enclave startup now work, then failed CA-backed hostname verification because mcpg v0.4.11 certificates covered only localhost/127.0.0.1 while AWF correctly connects through awf-enclave-github-proxy. The compiler supplies that centralized fixed alias to the launcher and passes --tls-dns-name "$PROXY_ALIAS" alongside --tls. The proxy remains bridge-only with no published host port, and identity labels, masked handoffs, deferred MCP semantics, and primary-agent exclusions are unchanged.

Validation

• focused enclave workflow and default/enclave image-pin tests pass
• compiler build, formatting, shellcheck, schema freshness, action shell lint, and impacted Go tests pass
• all 294 repository workflows recompile successfully
• exact copied gh-aw-firewall smoke-enclave-issues-read.md compilation: 1 succeeded, 0 warnings
• generated artifacts contain no v0.28.8 workflow pins and include immutable v0.28.9 pins for the standard and enclave AWF images
• generated lock inspection confirms the mcpg v0.4.12 digest pin, fixed TLS alias, masked gateway-key handoff, deferred awf-enclave route, and primary-agent exclusions

make agent-report-progress remains non-zero for the repository's existing function-length custom-linter baseline; this local worktree also reported a stale parallel golangci-lint runner. On macOS, the standalone MCP checker harness's healthy-server cases require GNU date/head; shellcheck passes and the enclave-specific fail-closed/deferred cases pass.

Dependencies

This remains a draft dependency-layer PR and should merge after the corresponding gh-aw-mcpg and AWF changes. AWF v0.28.9 and mcpg v0.4.12 are published. AWF v0.28.9 includes the protected enclave agent startup/entrypoint diagnostics from gh-aw-firewall#7772; mcpg v0.4.12 includes the required issues-read-v1 and repeatable --tls-dns-name contracts.

Pinned release images:

• ghcr.io/github/gh-aw-firewall/agent:0.28.9@sha256:54b2fb3068efc15a4cc1bd4033f8fa056a9b1779baeba0cb80ae95ea55e7e343
• ghcr.io/github/gh-aw-firewall/api-proxy:0.28.9@sha256:a0ffb1dc926c6e5a500b336893e032a8f167d3db43c869be886874ef14280bb8
• ghcr.io/github/gh-aw-firewall/cli-proxy:0.28.9@sha256:38d7ac0585ee5aa6a06eb71e087d514b059db36005c7783c6485e0dfd36fea35
• ghcr.io/github/gh-aw-firewall/squid:0.28.9@sha256:3d5dba0b0a139bbb11b5d5b8b44f277d2b18f69cf43090e3c283d750cf864baa
• ghcr.io/github/gh-aw-firewall/enclave-agent:0.28.9@sha256:8d548153f18d9b44406bebe3f71e2e080c15c89cbf8c0f72e8aa7bc0681efcf2
• ghcr.io/github/gh-aw-firewall/enclave-mcp-server:0.28.9@sha256:9edfa59fe0cf96f86c0be2f3280743a95032cf730526a204f729a06fbe7e4727
• ghcr.io/github/gh-aw-firewall/enclave-script:0.28.9@sha256:def4cc9669c0723cbdcdcdbd0ad4c72b6d977c02e4e0978797e9116fffd8e25d
• ghcr.io/github/gh-aw-mcpg:v0.4.12@sha256:92d5377b6bd32cd5b9306b2a553f7ef3549bccff9207e46f931e7249bc718713

The AWF v0.28.8 and v0.28.9 canonical config schema/spec blobs are identical, so no embedded schema or config-source spec update is required.

[Copilot]

Pull request overview

Adds isolated, read-only GitHub Issues access for agent enclaves through a dedicated mcpg proxy.

Changes:

• Adds issues-read-v1 schemas, validation, and version gates.
• Generates proxy policy, lifecycle, credential isolation, and tests.
• Documents routes, DIFC behavior, and dependency requirements.

Show a summary per file

File	Description
.changeset/enclave-github-issues-profile.md	Records the new profile.
.github/aw/enclaves.md	Adds authoring guidance.
actions/setup/sh/start_enclave_github_proxy.sh	Starts and configures the proxy.
actions/setup/sh/stop_enclave_github_proxy.sh	Cleans up proxy resources.
docs/src/content/docs/reference/enclaves.md	Documents profile behavior.
docs/src/content/docs/reference/glossary.md	Updates enclave terminology.
pkg/constants/version_constants.go	Defines dependency minimums.
pkg/parser/schema_test.go	Tests frontmatter validation.
pkg/parser/schemas/main_workflow_schema.json	Adds user-facing schema syntax.
pkg/workflow/awf_env.go	Excludes proxy handoff variables.
pkg/workflow/compiler_yaml_ai_execution.go	Adds proxy cleanup lifecycle.
pkg/workflow/enclave_github_proxy.go	Builds policy and lifecycle steps.
pkg/workflow/enclave_github_proxy_test.go	Tests proxy integration.
pkg/workflow/enclaves.go	Adds configuration and validation.
pkg/workflow/enclaves_test.go	Tests AWF configuration output.
pkg/workflow/mcp_setup_generator.go	Starts the proxy during MCP setup.
pkg/workflow/schemas/awf-config.schema.json	Adds AWF schema support.
schema-demos/schema-demo-enclaves.md	Demonstrates the new syntax.

Review details

Suppressed comments (1)

actions/setup/sh/start_enclave_github_proxy.sh:66

• A cancelled prior run can leave proxy-tls/ca.crt here. Because the readiness probe uses curl -k, it can accept the new proxy while retaining the stale CA, after which AWF receives a CA that cannot authenticate the proxy. Remove the previous container and log/TLS directory before recreating it.

mkdir -p "$MCP_LOG_DIR"
chmod 700 "$MCP_LOG_DIR"
docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true

• Files reviewed: 18/18 changed files
• Comments generated: 2
• Review effort level: Balanced

[pelikhan]

/matt

[pelikhan]

/review

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

🔎 Code quality review by PR Code Quality Reviewer

[github-actions]

Comment Memory

reviewed_at: 2026-08-24T00:00:00Z
review_event: REQUEST_CHANGES
top_themes:
  - enclave GitHub repo-limit validation incorrectly spans mixed enclave types
  - proxy teardown can be skipped after downstream host-step failures
files_reviewed:
  - .github/aw/enclaves.md
  - actions/setup/sh/start_enclave_github_proxy.sh
  - actions/setup/sh/stop_enclave_github_proxy.sh
  - docs/src/content/docs/reference/enclaves.md
  - docs/src/content/docs/reference/glossary.md
  - pkg/constants/version_constants.go
  - pkg/parser/schema_test.go
  - pkg/parser/schemas/main_workflow_schema.json
  - pkg/workflow/awf_env.go
  - pkg/workflow/compiler_yaml_ai_execution.go
  - pkg/workflow/enclave_github_proxy.go
  - pkg/workflow/enclave_github_proxy_test.go
  - pkg/workflow/enclaves.go
  - pkg/workflow/enclaves_test.go
  - pkg/workflow/mcp_setup_generator.go
  - pkg/workflow/schemas/awf-config.schema.json
  - schema-demos/schema-demo-enclaves.md
comment_count: 2

Note

This comment is managed by comment memory.

It stores persistent context for this thread in the code block at the top of this comment.
Edit only the text inside the backtick fences; workflow metadata and the footer are regenerated automatically.

Learn more about comment memory

🔎 Code quality review by PR Code Quality Reviewer · pi · gpt54 · 9.7 AIC · ⌖ 7.12 AIC · ⊞ 7K · ◷
_{Comment /review to run again}

[github-actions]

Request changes

This introduces two blocking regressions: the new repo-limit validation rejects valid mixed script + agent.github.cli enclave configs, and the enclave GitHub proxy teardown can be skipped when later host-side steps fail.

Blocking themes

• The issues-read-v1 non-public repository limit is being enforced against the wrong scope, so existing mixed-enclave workflows break as soon as they opt into the new profile.
• The proxy cleanup path is not robust against downstream failures, which leaves the capability handoff and proxy state alive longer than the design claims.

🔎 Code quality review by PR Code Quality Reviewer · pi · gpt54 · 9.7 AIC · ⌖ 7.12 AIC · ⊞ 7K
_{Comment /review to run again}

[github-actions]

Skills-Based Review 🧠

Applied /codebase-design and /tdd — overall LGTM with two minor observations (no blocking issues).

📋 Key Themes & Highlights

Key Themes

• Architecture is clean and well-scoped: the PAT/capability key never reaches the AWF sandbox or agent, the proxy runs in bridge mode with no published host port, and the stop step always clears the key from GITHUB_ENV. The security boundary is deliberately layered and the test suite enforces the contract.
• Version gating is conservative: provisional minimums (AWF v0.28.6, MCPG v0.4.11) are separated from global defaults until release artifacts exist. The validateEnclaveGitHubIssuesVersions function correctly uses the default MCPG version as the fallback when none is specified — meaning omitting sandbox.mcp.version fails validation.
• Two minor observations posted as inline comments:
  1. enclaveGitHubIssuesOperations as a package-level slice makes profile-to-operations lookup implicit; worth a map when a second profile arrives.
  2. A test case for the nil-MCP-config rejection path would complete the version-gate coverage.

Positive Highlights

• ✅ TestEnclaveGitHubProxyScriptsEnforceDedicatedBridgeContract is an excellent contract-enforcement test — it pins security-critical shell invariants (no -p host port, bridge mode, capability masking ordering) directly in Go.
• ✅ TestCompileEnclaveGitHubProxyLifecycle verifies end-to-end compilation ordering and exclusion of all handoff vars from the AWF command line.
• ✅ effectivePrimaryGitHubIntegrityFloor correctly prefers ParsedTools over raw map access and falls back to approved — the priority chain is explicit and tested.
• ✅ Refactoring validateEnclavesConfig into validateEnclaveEntry / validateEnclaveRepositories / validateEnclaveGitHubIssuesVersions meaningfully improves testability and readability.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · copilot · sonnet46 · 78.7 AIC · ⌖ 10.2 AIC · ⊞ 7.6K
_{Comment /matt to run again}

[gh-aw-bot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.

Please do one focused follow-up pass:

• address the blocking github-actions review that flagged mixed-enclave repo-limit validation scope and proxy teardown robustness
• respond in the existing review threads, push the fixes, and rerun the relevant checks
• refresh the branch if needed and use the pr-finisher skill before handing back for review

Run: https://github.com/github/gh-aw/actions/runs/32787277683

Generated by 👨🍳 PR Sous Chef

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 20.4 AIC · ⌖ 9.41 AIC · ⊞ 8.7K · ◷
_{Comment /souschef to run again}

[Copilot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.
...

Addressed in efa862c. I added focused regression coverage for mixed-enclave repository-limit scoping and for unconditional enclave GitHub proxy teardown (if: always() + continue-on-error) so these behaviors are now explicitly guarded.

[gh-aw-bot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.

Please do one focused follow-up pass:

• the prior sous-chef nudge has a follow-up from the PR author-side agent, but the PR still shows CHANGES_REQUESTED; please reply in the blocking github-actions review thread(s) with the concrete fix references and ensure the blocking review is fully addressed
• refresh the branch if needed and use the pr-finisher skill before handing back for review

Run: https://github.com/github/gh-aw/actions/runs/32795790586

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 14.8 AIC · ⌖ 9.31 AIC · ⊞ 8.7K · ◷
_{Comment /souschef to run again}

[Copilot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.
...

Follow-up done. I replied in the blocking github-actions review threads with concrete fix references to efa862c for both items (TestValidateEnclaveGitHubIssuesRepositoryLimitScopesToGitHubEntry and TestGenerateEnclaveGitHubProxyStopAlwaysRuns). The branch is refreshed at 5c0a988.

done

[lpcox]

@copilot address all review feedback

[Copilot]

@copilot address all review feedback

Done on current head c71821d: all review threads are now addressed and marked resolved, including the prior Copilot and github-actions feedback items. I also rechecked recent PR runs on this head (32918097721, 32918097732, 32918097782, 32918111663), and they are completed/success with no failed jobs.

[gh-aw-bot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.

Please do one focused follow-up pass:

• review the current PR state, refresh the branch if needed, and make sure any missing maintainer-facing context is added
• run the pr-finisher skill before handing back for review

Run: https://github.com/github/gh-aw/actions/runs/32957620001

Generated by 👨🍳 PR Sous Chef

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 13.3 AIC · ⌖ 8.12 AIC · ⊞ 8.7K · ◷
_{Comment /souschef to run again}

[Copilot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.
...

Current PR state checked on head c71821d: review threads are resolved and prior feedback is addressed, and the cited run 32957620001 has no failed jobs. Maintainer-facing gap now appears to be mergeability (mergeable_state: dirty), so the branch likely needs a refresh/conflict resolution against main before final merge.

[gh-aw-bot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.

Please do one focused follow-up pass:

• this PR is currently merge-conflicting (DIRTY); run make merge-main to resolve conflicts against main, then rerun the relevant validation
• after resolving conflicts, make sure maintainer-facing context stays explicit and use the pr-finisher skill before handing back for review

Run: https://github.com/github/gh-aw/actions/runs/32962488926

Generated by 👨‍🍳 PR Sous Chef · pi · gpt54 · 18.5 AIC · ⌖ 8.2 AIC · ⊞ 6.3K · ◷
_{Comment /souschef to run again}

[Copilot]

gh-aw-pr-sous-chef
@copilot PR Sous Chef triage: this PR still needs a forward-progress pass before maintainer investigation is likely to be productive.
...

Completed. I ran make merge-main, resolved the resulting lockfile conflicts, and finalized the merge on this branch (e786f2f + lockfile recompile follow-up 8469fe9). I then reran relevant validation (go test ./pkg/workflow -run 'Enclave|enclave', go test ./pkg/parser -run 'Schema|Enclave|enclave', make shellcheck-setup-sh, make build, make check-stale-schema-binary, make recompile, make fmt). The cited run 32962488926 also shows no failed jobs.

[pelikhan]

@copilot resolve the merge conflicts on this branch.

[Copilot]

@copilot resolve the merge conflicts on this branch.

Done — merge conflicts on this branch have been resolved. I merged main with make merge-main, resolved the lockfile conflicts, and finalized with e786f2f plus lockfile recompile commit 8469fe9. Current branch is clean with no in-progress merge state.