Add features.awf-diagnostic-logs to enable AWF failure diagnostics artifact collection

docs/src/content/docs/reference/frontmatter.md

@@ -434,6 +434,17 @@ Without this flag, BYOK mode requires manual composition of all three behaviors.
 > [!NOTE]
 > `byok-copilot` applies only to `engine: copilot` workflows. The implicit `cli-proxy` enablement does not apply to other engines.
 
+#### AWF Failure Diagnostics (`features.awf-diagnostic-logs`)
+
+Enables AWF Docker operational diagnostics collection on failure by adding `--diagnostic-logs` to AWF runtime arguments.
+
+When enabled, AWF includes failure diagnostics under the `diagnostics/` subdirectory in the `firewall-audit-logs` artifact (for example, container logs, exit codes, mount metadata, and sanitized compose configuration).
+
+```yaml wrap
+features:
+  awf-diagnostic-logs: true
+```
+
 #### Reaction-based Trust Signals (`features.integrity-reactions`)
 
 Enables maintainers to promote or demote content past the integrity filter using GitHub reactions (👍, ❤️, 👎, 😕), without adding labels or modifying issue state. Available from gh-aw v0.68.2.

docs/src/content/docs/reference/glossary.md

@@ -291,7 +291,7 @@ See [Engines Reference](/gh-aw/reference/engines/).
 
 ### Feature Flags (`features:`)
 
-A frontmatter section that enables experimental or optional compiler and runtime behaviors as key-value pairs. Feature flags provide controlled access to new capabilities before they become defaults or are fully stabilized. Common flags include `action-mode` (controls how custom action references are compiled), `copilot-requests` (enables GitHub Actions token authentication for Copilot; currently in **private preview** — will not work unless your account has been onboarded), `byok-copilot` (enables Copilot offline BYOK mode with dummy `COPILOT_API_KEY`, API proxy sidecar, implicit `cli-proxy`, and latest Copilot CLI install), `mcp-gateway` (enables the MCP gateway proxy), `integrity-reactions` (enables reaction-based integrity promotion and demotion), and `cli-proxy` (enables CLI proxy mode for integrity enforcement at the network boundary). See [Frontmatter Reference](/gh-aw/reference/frontmatter/#feature-flags-features).
+A frontmatter section that enables experimental or optional compiler and runtime behaviors as key-value pairs. Feature flags provide controlled access to new capabilities before they become defaults or are fully stabilized. Common flags include `action-mode` (controls how custom action references are compiled), `copilot-requests` (enables GitHub Actions token authentication for Copilot; currently in **private preview** — will not work unless your account has been onboarded), `byok-copilot` (enables Copilot offline BYOK mode with dummy `COPILOT_API_KEY`, API proxy sidecar, implicit `cli-proxy`, and latest Copilot CLI install), `mcp-gateway` (enables the MCP gateway proxy), `integrity-reactions` (enables reaction-based integrity promotion and demotion), `cli-proxy` (enables CLI proxy mode for integrity enforcement at the network boundary), and `awf-diagnostic-logs` (enables AWF Docker operational diagnostics collection on failure). See [Frontmatter Reference](/gh-aw/reference/frontmatter/#feature-flags-features).
 
 ### Fuzzy Scheduling
 

pkg/constants/constants_test.go

@@ -332,6 +332,7 @@ func TestFeatureFlagConstants(t *testing.T) {
 		{"MCPGatewayFeatureFlag", MCPGatewayFeatureFlag, "mcp-gateway"},
 		{"DisableXPIAPromptFeatureFlag", DisableXPIAPromptFeatureFlag, "disable-xpia-prompt"},
 		{"DIFCProxyFeatureFlag", DIFCProxyFeatureFlag, "difc-proxy"},
+		{"AwfDiagnosticLogsFeatureFlag", AwfDiagnosticLogsFeatureFlag, "awf-diagnostic-logs"},
 	}
 
 	for _, tt := range tests {

pkg/constants/feature_constants.go

@@ -39,6 +39,16 @@ const (
 	//	features:
 	//	  cli-proxy: true
 	CliProxyFeatureFlag FeatureFlag = "cli-proxy"
+	// AwfDiagnosticLogsFeatureFlag enables AWF operational Docker diagnostics
+	// collection on failure. When enabled, AWF collects capped container logs,
+	// container exit codes, mount metadata, and sanitized compose config into
+	// the diagnostics subdirectory of the firewall audit artifact.
+	//
+	// Workflow frontmatter usage:
+	//
+	//	features:
+	//	  awf-diagnostic-logs: true
+	AwfDiagnosticLogsFeatureFlag FeatureFlag = "awf-diagnostic-logs"
 	// CopilotIntegrationIDFeatureFlag gates injection of the
 	// GITHUB_COPILOT_INTEGRATION_ID environment variable into the agent step.
 	// Default off — the env var may cause Copilot CLI failures.

pkg/workflow/awf_helpers.go

@@ -246,6 +246,10 @@ func BuildAWFArgs(config AWFCommandConfig) []string {
 	awfArgs = append(awfArgs, "--log-level", awfLogLevel)
 	awfArgs = append(awfArgs, "--proxy-logs-dir", string(constants.AWFProxyLogsDir))
 	awfArgs = append(awfArgs, "--audit-dir", string(constants.AWFAuditDir))
+	if isFeatureEnabled(constants.AwfDiagnosticLogsFeatureFlag, config.WorkflowData) {
+		awfArgs = append(awfArgs, "--diagnostic-logs")
+		awfHelpersLog.Print("Added --diagnostic-logs because awf-diagnostic-logs feature flag is enabled")
+	}
 
 	// Always add --enable-host-access: needed for the API proxy sidecar
 	// (to reach host.docker.internal:<port>) and for MCP gateway communication

pkg/workflow/awf_helpers_test.go

@@ -426,6 +426,51 @@ func TestBuildAWFArgsAuditDir(t *testing.T) {
 	})
 }
 
+// TestBuildAWFArgsDiagnosticLogs tests that BuildAWFArgs includes --diagnostic-logs
+// only when features.awf-diagnostic-logs is enabled.
+func TestBuildAWFArgsDiagnosticLogs(t *testing.T) {
+	baseWorkflow := func(features map[string]any) *WorkflowData {
+		return &WorkflowData{
+			Name: "test-workflow",
+			EngineConfig: &EngineConfig{
+				ID: "copilot",
+			},
+			NetworkPermissions: &NetworkPermissions{
+				Firewall: &FirewallConfig{Enabled: true},
+			},
+			Features: features,
+		}
+	}
+
+	t.Run("does not include --diagnostic-logs when feature flag is absent", func(t *testing.T) {
+		config := AWFCommandConfig{
+			EngineName:     "copilot",
+			WorkflowData:   baseWorkflow(nil),
+			AllowedDomains: "github.com",
+		}
+
+		args := BuildAWFArgs(config)
+		argsStr := strings.Join(args, " ")
+
+		assert.NotContains(t, argsStr, "--diagnostic-logs", "Should not include --diagnostic-logs when feature flag is absent")
+	})
+
+	t.Run("includes --diagnostic-logs when awf-diagnostic-logs is enabled", func(t *testing.T) {
+		config := AWFCommandConfig{
+			EngineName: "copilot",
+			WorkflowData: baseWorkflow(map[string]any{
+				string(constants.AwfDiagnosticLogsFeatureFlag): true,
+			}),
+			AllowedDomains: "github.com",
+		}
+
+		args := BuildAWFArgs(config)
+		argsStr := strings.Join(args, " ")
+
+		assert.Contains(t, argsStr, "--diagnostic-logs", "Should include --diagnostic-logs when feature flag is enabled")
+	})
+}
+
 // TestBuildAWFArgsMemoryLimit tests that BuildAWFArgs passes --memory-limit
 // when sandbox.agent.memory is configured in the workflow frontmatter
 func TestBuildAWFArgsMemoryLimit(t *testing.T) {