Wire dynamic enclave delegation controller env vars and fix primary-agent isolation

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Author: Copilot

docs/src/content/docs/experimental/enclaves.md

@@ -71,7 +71,7 @@ sandbox:
     id: awf
     version: v0.28.14
   mcp:
-    version: v0.4.16
+    version: v0.4.17
 enclaves:
   - agent:
       model: gpt-5
@@ -102,8 +102,8 @@ enclaves:
 - An entry must declare either non-empty static `repos` or `dynamic`, never both.
 - `allowed-owners` and `allowed-repositories` use canonical lowercase ASCII selectors. Repository selectors must already match `owner/repo`; the compiler does not trim, case-fold, URL-decode, or normalize them.
 - `github-policy` must be `github-repository-read-v1`, which exposes only `list_issues` and `issue_read` through per-invocation delegated identities.
-- Dynamic entries require finite resource limits, total quotas, audit labels, an absolute `expires-at` no later than the enclave job lifetime, AWF `v0.28.14` or newer, and mcpg `v0.4.16` or newer.
-- The primary and enclave agents do not receive repository credentials or the delegation-control capability. The compiler gives AWF an AWF-only control capability so AWF can request short-lived mcpg identities for admitted repositories.
+- Dynamic entries require finite resource limits, total quotas, audit labels, an absolute `expires-at` timestamp, AWF `v0.28.14` or newer, and mcpg `v0.4.17` or newer (the first mcpg release that accepts the delegation controller's atomic bootstrap configuration; see `github/gh-aw-mcpg#12605`). `expires-at` is an upper bound checked into the workflow file; the compiler resolves the effective envelope expiry at workflow setup time as `min(expires-at, job-start + enclave timeout)`, so a fixed, checked-in timestamp never needs to be a short-lived compile-time value.
+- The primary and enclave agents do not receive repository credentials or the delegation-control capability. The compiler starts mcpg's `github-repository-delegation-v1` controller with five settings as one atomic configuration (`MCP_GATEWAY_DELEGATION_ENVELOPE`, `MCP_GATEWAY_DELEGATION_CONTROL_KEY`, `MCP_GATEWAY_DELEGATION_STATE_PATH`, `MCP_GATEWAY_DELEGATION_GENERATION`, `MCP_GATEWAY_DELEGATION_CONTROL_LISTEN`) and hands AWF an explicit, host-private control endpoint (`AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_ENDPOINT`) and capability so AWF can request short-lived mcpg identities for admitted repositories. That endpoint is distinct from the executor-facing `AWF_ENCLAVE_MCP_GATEWAY_ENDPOINT` data plane and is excluded from the primary agent's environment.
 
 ## Deprecated `issues-read-v1` profile
 

pkg/constants/version_constants.go

@@ -169,6 +169,11 @@ const AWFEnclaveTrustedSensitivityMinVersion Version = "v0.28.14"
 // AWFDynamicRepositoryEnclaveMinVersion is the first AWF version that accepts
 // dynamic agent enclave repository policy envelopes and performs per-invocation
 // repository admission through MCPG's github-repository-delegation-v1 controller.
+//
+// This value is intentionally kept above DefaultFirewallVersion (provisional,
+// fail-closed) until the AWF implementation tracked by gh-aw-firewall#8195
+// ships. Once that release is available, raise this constant to the actual
+// compatible AWF release and update DefaultFirewallVersion accordingly.
 const AWFDynamicRepositoryEnclaveMinVersion Version = "v0.28.14"
 
 // AWFAPIProxyCACertMinVersion is the minimum AWF version that supports
@@ -226,7 +231,17 @@ const MCPGEnclaveAgentToolsMinVersion Version = "v0.4.15"
 // MCPGDynamicRepositoryDelegationMinVersion is the first MCPG version that
 // advertises the github-repository-delegation-v1 dynamic repository delegation
 // controller required by dynamic agent enclave admission.
-const MCPGDynamicRepositoryDelegationMinVersion Version = "v0.4.16"
+//
+// v0.4.16 advertised the controller but rejected the strict-stdin
+// "delegationControllers" config field the compiler previously emitted, never
+// started the real controller, and never handed AWF a private control
+// endpoint (gh-aw-mcpg#12604). That contract is fixed by gh-aw-mcpg#12605; this
+// constant is pinned to the first release containing that fix so dynamic
+// enclave compilation/runtime setup fails closed on older MCPG builds that
+// lack the compatible owner-scoped envelope, bounded dynamic schema
+// admission, transactional reconciliation, persisted TTL binding, durability,
+// DIFC isolation, and redaction behavior.
+const MCPGDynamicRepositoryDelegationMinVersion Version = "v0.4.17"
 
 // DefaultPlaywrightCLIVersion is the default version of the @playwright/cli package.
 // Used when tools.playwright is enabled.

pkg/workflow/awf_env.go

@@ -170,6 +170,9 @@ func ComputeAWFExcludeEnvVarNames(workflowData *WorkflowData, coreSecretVarNames
 	if enclaveGitHubIssuesEnabled(workflowData) {
 		addUnique(enclaveGitHubMCPAgentIDEnv)
 	}
+	if enclaveDynamicRepositoryPolicyEnabled(workflowData) {
+		addUnique(enclaveGitHubDelegationControlEndpointEnv)
+	}
 
 	// Explicitly excluded env vars from the frontmatter excluded-env field.
 	// These are always excluded regardless of their value content.

pkg/workflow/enclave_github_proxy_test.go

@@ -103,9 +103,20 @@ func TestDynamicEnclaveRegistersGitHubBackend(t *testing.T) {
 	data := dynamicEnclaveWorkflowData()
 	config := buildMCPGatewayConfig(data)
 
+	// The GitHub backend stays registered so mcpg's delegation controller can
+	// issue delegated identities for it, but the primary agent identity must
+	// not gain GitHub MCP access merely because a dynamic enclave is enabled.
 	assert.Contains(t, collectMCPTools(data), "github")
+	assert.NotContains(t, config.AgentPolicies["${MCP_GATEWAY_AGENT_ID}"].Servers, "github")
+}
+
+func TestDynamicEnclaveWithPrimaryGitHubRetainsPrimaryAccess(t *testing.T) {
+	data := dynamicEnclaveWorkflowData()
+	data.Tools["github"] = map[string]any{}
+	config := buildMCPGatewayConfig(data)
+
 	assert.Contains(t, config.AgentPolicies["${MCP_GATEWAY_AGENT_ID}"].Servers, "github")
-	assert.Equal(t, "github", config.DelegationControllers[enclaveDynamicController].Server)
+	assert.NotEmpty(t, config.AgentPolicies["${MCP_GATEWAY_AGENT_ID}"].Tools["github"])
 }
 
 func TestCompileEnclaveGitHubSharedGateway(t *testing.T) {

pkg/workflow/enclaves.go

@@ -26,15 +26,40 @@ const (
 	enclaveMCPReadinessTimeoutEnv = "AWF_ENCLAVE_MCP_READINESS_TIMEOUT_MS"
 	enclaveMCPDeferredServersEnv  = "GH_AW_MCP_DEFERRED_SERVERS"
 	enclaveGitHubDelegationEnv    = "AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_CAPABILITY"
-	enclaveMCPGatewayRunLabel     = "com.github.gh-aw.mcpg.run"
-	enclaveMCPGatewayContainer    = "awmg-mcpg"
-	enclaveGitHubIssuesProfile    = "issues-read-v1"
-	enclaveDynamicGitHubPolicy    = "github-repository-read-v1"
-	enclaveDynamicController      = "github-repository-delegation-v1"
-	enclaveMCPConnectTimeout      = 120
-	enclaveMCPReadinessTimeoutMS  = 120000
-	maxEnclaveTimingBucketSeconds = 4800
-	enclaveMCPTransportAllowance  = 60
+	// enclaveGitHubDelegationControlEndpointEnv identifies the AWF-private control
+	// endpoint for mcpg's github-repository-delegation-v1 controller. This is
+	// distinct from enclaveMCPGatewayEndpointEnv, which identifies the
+	// executor-facing /mcp/awf-enclave data plane. Only the AWF host process
+	// receives this variable; it must never reach the primary agent or the
+	// enclave executor.
+	enclaveGitHubDelegationControlEndpointEnv = "AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_ENDPOINT"
+	enclaveMCPGatewayRunLabel                 = "com.github.gh-aw.mcpg.run"
+	enclaveMCPGatewayContainer                = "awmg-mcpg"
+	enclaveGitHubIssuesProfile                = "issues-read-v1"
+	enclaveDynamicGitHubPolicy                = "github-repository-read-v1"
+	enclaveDynamicController                  = "github-repository-delegation-v1"
+	enclaveMCPConnectTimeout                  = 120
+	enclaveMCPReadinessTimeoutMS              = 120000
+	maxEnclaveTimingBucketSeconds             = 4800
+	enclaveMCPTransportAllowance              = 60
+	// enclaveDelegationControlPort is the private, host-only listener port for
+	// mcpg's github-repository-delegation-v1 control plane. It is bound
+	// separately from MCP_GATEWAY_PORT (the executor-facing data plane) and is
+	// published only to loopback so neither the primary agent nor the enclave
+	// executor network can route to it.
+	enclaveDelegationControlPort = 8090
+	// enclaveDelegationStateDir is the protected, persistent mount used for mcpg
+	// delegation controller state so that it survives an in-run restart.
+	enclaveDelegationStateDir = "${RUNNER_TEMP}/gh-aw/mcpg-delegation"
+	// enclaveDelegationGeneration is the monotonic policy generation for the
+	// active envelope. It is fixed for the lifetime of a single workflow run so
+	// that controller restart/recovery within the run observes a stable value.
+	enclaveDelegationGeneration = "1"
+	// enclaveDelegationExpiresAtEnv holds the runtime-resolved RFC3339 envelope
+	// expiry: min(enclaves[].dynamic.expires-at, job-start + enclave.timeout).
+	// This keeps checked-in workflows valid without requiring a short-lived
+	// absolute compile-time timestamp.
+	enclaveDelegationExpiresAtEnv = "MCP_GATEWAY_DELEGATION_EXPIRES_AT"
 )
 
 var enclaveAgentGitHubSupportedTools = map[string]struct{}{
@@ -396,13 +421,14 @@ func validateDynamicEnclavePolicy(index int, enclave *EnclaveConfig) error {
 }
 
 func validateDynamicEnclaveBounds(index int, enclave *EnclaveConfig, policy *DynamicEnclavePolicy) error {
-	expiresAt, err := time.Parse(time.RFC3339, policy.ExpiresAt)
-	if err != nil {
+	if _, err := time.Parse(time.RFC3339, policy.ExpiresAt); err != nil {
 		return fmt.Errorf("enclaves[%d].dynamic.expires-at must be an absolute RFC3339 timestamp: %w", index, err)
 	}
-	if expiresAt.After(time.Now().UTC().Add(time.Duration(enclave.Timeout) * time.Second)) {
-		return fmt.Errorf("enclaves[%d].dynamic.expires-at must not exceed the enclave job lifetime", index)
-	}
+	// expires-at is an upper bound only. Checked-in workflows may carry a
+	// fixed timestamp that grows stale between commits, so the compiler does
+	// not compare it against compile-time time.Now(); the runtime/job-relative
+	// expiry contract instead clamps the effective envelope expiry to
+	// min(expires-at, job-start + enclave.timeout) when the workflow runs.
 	cpuLimit, err := strconv.ParseFloat(enclave.CPULimit, 64)
 	if err != nil || cpuLimit <= 0 {
 		return fmt.Errorf("enclaves[%d].cpu-limit must be a positive finite value", index)
@@ -677,6 +703,48 @@ func buildAWFDynamicEnclavePolicy(enclave *EnclaveConfig) map[string]any {
 	}
 }
 
+// buildMCPGatewayDelegationEnvelope produces the immutable envelope handed to mcpg's
+// github-repository-delegation-v1 controller via MCP_GATEWAY_DELEGATION_ENVELOPE.
+// The envelope represents owner-scoped runtime discovery, an optional exact repository
+// allowlist, the bounded dynamic schema-hash capacity, the exact v1 tool set, the
+// maximum identity TTL, and the runtime expiry, without broadening authority beyond
+// what enclaves[].dynamic declares at compile time.
+func buildMCPGatewayDelegationEnvelope(enclave *EnclaveConfig) map[string]any {
+	policy := enclave.Dynamic
+	return map[string]any{
+		"version":               enclaveDynamicGitHubPolicy,
+		"runId":                 "${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}",
+		"backend":               "github",
+		"allowedOwners":         stringSliceOrEmpty(policy.AllowedOwners),
+		"allowedRepositories":   stringSliceOrEmpty(policy.AllowedRepositories),
+		"tools":                 append([]string(nil), enclaveAgentGitHubDefaultTools...),
+		"maxSchemaHashes":       policy.MaxRepositories,
+		"maxIdentityTTLSeconds": enclave.Timeout,
+		"expiresAt":             "${" + enclaveDelegationExpiresAtEnv + "}",
+		"generation":            enclaveDelegationGeneration,
+		"auditLabels":           append([]string(nil), policy.AuditLabels...),
+	}
+}
+
+// buildDynamicEnclaveExpiryScript emits the shell lines that resolve the
+// runtime/job-relative envelope expiry contract: the effective expiry is the
+// earlier of the compiled enclaves[].dynamic.expires-at upper bound and
+// job-start + enclave.timeout, so it can never exceed the job or invocation
+// lifetime regardless of how stale a checked-in absolute timestamp has grown.
+func buildDynamicEnclaveExpiryScript(enclave *EnclaveConfig) string {
+	var script strings.Builder
+	fmt.Fprintf(&script, "          GH_AW_ENCLAVE_DYNAMIC_JOB_EXPIRES_EPOCH=$(( $(date -u +%%s) + %d ))\n", enclave.Timeout)
+	fmt.Fprintf(&script, "          GH_AW_ENCLAVE_DYNAMIC_CONFIGURED_EXPIRES_EPOCH=$(date -u -d %s +%%s)\n", shellEscapeArg(enclave.Dynamic.ExpiresAt))
+	script.WriteString("          if [ \"$GH_AW_ENCLAVE_DYNAMIC_CONFIGURED_EXPIRES_EPOCH\" -lt \"$GH_AW_ENCLAVE_DYNAMIC_JOB_EXPIRES_EPOCH\" ]; then\n")
+	script.WriteString("            GH_AW_ENCLAVE_DYNAMIC_EXPIRES_EPOCH=\"$GH_AW_ENCLAVE_DYNAMIC_CONFIGURED_EXPIRES_EPOCH\"\n")
+	script.WriteString("          else\n")
+	script.WriteString("            GH_AW_ENCLAVE_DYNAMIC_EXPIRES_EPOCH=\"$GH_AW_ENCLAVE_DYNAMIC_JOB_EXPIRES_EPOCH\"\n")
+	script.WriteString("          fi\n")
+	fmt.Fprintf(&script, "          %s=$(date -u -d \"@$GH_AW_ENCLAVE_DYNAMIC_EXPIRES_EPOCH\" +%%Y-%%m-%%dT%%H:%%M:%%SZ)\n", enclaveDelegationExpiresAtEnv)
+	fmt.Fprintf(&script, "          export %s\n", enclaveDelegationExpiresAtEnv)
+	return script.String()
+}
+
 func stringSliceOrEmpty(values []string) []string {
 	if values == nil {
 		return []string{}

pkg/workflow/enclaves_test.go

@@ -360,11 +360,19 @@ func TestBuildAWFConfigJSONDynamicEnclavePolicy(t *testing.T) {
 }
 
 func TestValidateDynamicEnclavePolicyBoundsExpiryAndCPU(t *testing.T) {
+	// expires-at is a checked-in upper bound; it must remain valid even after
+	// it has grown "stale" relative to compile time, since the runtime/job-
+	// relative expiry contract (not compile-time comparison) clamps the
+	// effective envelope expiry at workflow setup time.
 	data := dynamicEnclaveWorkflowData()
 	data.Enclaves[0].Dynamic.ExpiresAt = "2999-01-01T00:00:00Z"
+	require.NoError(t, validateEnclavesConfig(data))
+
+	data = dynamicEnclaveWorkflowData()
+	data.Enclaves[0].Dynamic.ExpiresAt = "not-a-timestamp"
 	err := validateEnclavesConfig(data)
 	require.Error(t, err)
-	assert.Contains(t, err.Error(), "must not exceed the enclave job lifetime")
+	assert.Contains(t, err.Error(), "must be an absolute RFC3339 timestamp")
 
 	data = dynamicEnclaveWorkflowData()
 	data.Enclaves[0].CPULimit = "0"
@@ -542,9 +550,9 @@ func TestValidateDynamicEnclavePolicy(t *testing.T) {
 		{
 			name: "rejects old mcpg version",
 			mutate: func(data *WorkflowData) {
-				data.SandboxConfig.MCP.Version = "v0.4.15"
+				data.SandboxConfig.MCP.Version = "v0.4.16"
 			},
-			errContains: "requires MCPG v0.4.16 or newer",
+			errContains: "requires MCPG v0.4.17 or newer",
 		},
 	}
 
@@ -566,30 +574,36 @@ func TestDynamicEnclaveGatewayContract(t *testing.T) {
 	require.NotNil(t, gateway)
 	assert.Equal(t, []string{"${MCP_GATEWAY_AGENT_ID}"}, gateway.AgentIDs)
 	assert.NotContains(t, gateway.AgentPolicies, "${AWF_ENCLAVE_GITHUB_MCP_AGENT_ID}")
-	controller := gateway.DelegationControllers[enclaveDynamicController]
-	assert.Equal(t, "github", controller.Server)
-	assert.Equal(t, map[string]any{
-		"version": enclaveDynamicGitHubPolicy,
-		"tools":   []string{"list_issues", "issue_read"},
-	}, controller.Policy)
-	assert.Equal(t, "${AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_CAPABILITY}", controller.ControlCapability)
 
 	var output strings.Builder
 	require.NoError(t, generateMCPGatewaySetup(
 		&output, data.Tools, []string{enclaveMCPServerName}, NewCopilotEngine(), data, false, nil,
 	))
 	generated := output.String()
-	assert.Contains(t, generated, `"delegationControllers": {"github-repository-delegation-v1"`)
-	assert.Contains(t, generated, `"version":"github-repository-read-v1"`)
-	assert.Contains(t, generated, `"tools":["list_issues","issue_read"]`)
+	// The gateway's strict-stdin config schema does not accept a
+	// "delegationControllers" field; the compiler must not emit one.
+	assert.NotContains(t, generated, `"delegationControllers"`)
+	// The five required settings are bootstrapped as one atomic configuration.
+	assert.Contains(t, generated, `export MCP_GATEWAY_DELEGATION_CONTROL_KEY="${AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_CAPABILITY}"`)
+	assert.Contains(t, generated, `export MCP_GATEWAY_DELEGATION_STATE_PATH="`)
+	assert.Contains(t, generated, `export MCP_GATEWAY_DELEGATION_GENERATION="1"`)
+	assert.Contains(t, generated, `export MCP_GATEWAY_DELEGATION_CONTROL_LISTEN="127.0.0.1:8090"`)
+	assert.Contains(t, generated, `export MCP_GATEWAY_DELEGATION_ENVELOPE=`)
+	assert.Contains(t, generated, `\"version\":\"github-repository-read-v1\"`)
+	assert.Contains(t, generated, `\"tools\":[\"list_issues\",\"issue_read\"]`)
+	assert.Contains(t, generated, `\"expiresAt\":\"${MCP_GATEWAY_DELEGATION_EXPIRES_AT}\"`)
+	// The private control endpoint is distinct from the executor-facing data plane.
+	assert.Contains(t, generated, `export AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_ENDPOINT="http://127.0.0.1:8090/control/github-repository-delegation-v1"`)
 	assert.Contains(t, generated, `AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_CAPABILITY=$(openssl rand -hex 32)`)
 	assert.Contains(t, generated, `::add-mask::${AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_CAPABILITY}`)
 	assert.Contains(t, generated, `printf '%s=%s\n' AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_CAPABILITY "$AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_CAPABILITY"`)
+	assert.Contains(t, generated, `printf '%s=%s\n' AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_ENDPOINT "$AWF_ENCLAVE_GITHUB_DELEGATION_CONTROL_ENDPOINT"`)
 	assert.NotContains(t, generated, `AWF_ENCLAVE_GITHUB_MCP_AGENT_ID=$(openssl rand`)
 
 	excluded := ComputeAWFExcludeEnvVarNames(data, nil)
 	assert.Contains(t, excluded, enclaveGitHubDelegationEnv)
 	assert.Contains(t, excluded, enclaveMCPCapabilityEnv)
+	assert.Contains(t, excluded, enclaveGitHubDelegationControlEndpointEnv)
 }
 
 func TestGenerateEnclaveGatewayContract(t *testing.T) {

pkg/workflow/mcp_gateway_config.go

@@ -217,7 +217,11 @@ func buildMCPGatewayConfig(workflowData *WorkflowData) *MCPGatewayRuntimeConfig
 		if githubTool, hasGitHub := workflowData.Tools["github"]; hasGitHub && githubTool != false {
 			primaryGitHubEnabled = !isGitHubCLIModeEnabled(workflowData)
 		}
-		if !primaryGitHubEnabled && !enclaveDynamicRepositoryPolicyEnabled(workflowData) {
+		// Dynamic repository delegation keeps the GitHub backend registered so
+		// mcpg-issued delegated identities can reach it, but the primary agent
+		// identity must not gain GitHub MCP access merely because a dynamic
+		// enclave is configured; it requires a separate top-level tools.github.
+		if !primaryGitHubEnabled {
 			for i, server := range primaryServers {
 				if server == "github" {
 					primaryServers = append(primaryServers[:i], primaryServers[i+1:]...)
@@ -241,18 +245,11 @@ func buildMCPGatewayConfig(workflowData *WorkflowData) *MCPGatewayRuntimeConfig
 				Tools:   map[string][]string{"github": collectGitHubMCPManifestTools(workflowData.Tools["github"])},
 			}
 		}
-		if enclaveDynamicRepositoryPolicyEnabled(workflowData) {
-			config.DelegationControllers = map[string]MCPGatewayDelegationController{
-				enclaveDynamicController: {
-					Server: "github",
-					Policy: map[string]any{
-						"version": enclaveDynamicGitHubPolicy,
-						"tools":   enclaveAgentGitHubDefaultTools,
-					},
-					ControlCapability: "${" + enclaveGitHubDelegationEnv + "}",
-				},
-			}
-		}
+		// Dynamic repository delegation is bootstrapped entirely through the five
+		// MCP_GATEWAY_DELEGATION_* environment variables set up in
+		// generateMCPGatewaySetup and forwarded via appendMCPGatewayConditionalEnvFlags.
+		// The gateway's strict-stdin config schema does not accept a
+		// "delegationControllers" field, so no value is emitted here.
 	}
 	return config
 }

pkg/workflow/mcp_renderer.go

@@ -208,13 +208,6 @@ func RenderJSONMCPConfig( //nolint:largefunc // Existing renderer keeps MCP JSON
 		} else {
 			fmt.Fprintf(&configBuilder, "              \"agentId\": \"%s\"", options.GatewayConfig.AgentID)
 		}
-		if len(options.GatewayConfig.DelegationControllers) > 0 {
-			delegationControllers, err := json.Marshal(options.GatewayConfig.DelegationControllers)
-			if err != nil {
-				return fmt.Errorf("failed to marshal gateway delegation controllers: %w", err)
-			}
-			fmt.Fprintf(&configBuilder, ",\n              \"delegationControllers\": %s", delegationControllers)
-		}
 
 		// Add optional fields if specified (agentId always precedes them without a trailing comma)
 		if options.GatewayConfig.PayloadDir != "" {