fix(security): address P2-8 Copilot review nits

- aead.go: docstring no longer claims "lowercase hex" only; hex.DecodeString
  accepts both cases, and constraining the wire form would just be a foot-gun.
- aead.go: ErrKeyRequired message no longer points to --generate-webhook-secret
  as the recovery path. That flag won't overwrite an existing file, so it
  wouldn't actually unblock recovery for an encrypted webhook secret. The
  doc comment for ErrKeyRequired explains this; the message itself just
  says "delete the file and re-generate the secret".
- main.go: plaintext-encryption warning moved out of the one-shot CLI
  handler region (was firing before --show-api-key etc., polluting their
  stdout). Now only emitted on normal startup. Malformed-key validation
  still runs early so any subcommand that needs to decrypt fails cleanly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sarg3nt

gearbox-agent/cmd/gearbox-agent/main.go

@@ -92,14 +92,12 @@ func main() {
 		Level: logLevel,
 	}))
 
-	// Warn once at startup if secret-file encryption is not configured.
-	if ok, err := crypto.EncryptionConfigured(); err != nil {
+	// Hard-fail early if GEARBOX_AGENT_ENCRYPTION_KEY is set but malformed,
+	// regardless of which subcommand we're about to run — one-shot CLI
+	// commands like --show-api-key need a usable key too.
+	if _, err := crypto.EncryptionConfigured(); err != nil {
 		fmt.Fprintf(os.Stderr, "Encryption key configuration error: %v\n", err)
 		os.Exit(1)
-	} else if !ok {
-		logger.Warn("Secret files are stored in plaintext. " +
-			"Set GEARBOX_AGENT_ENCRYPTION_KEY (64 hex chars, see 'openssl rand -hex 32') " +
-			"to enable AES-256-GCM encryption-at-rest.")
 	}
 
 	// Handle API key commands
@@ -179,6 +177,15 @@ func main() {
 		"built", BuildDate,
 	)
 
+	// Warn once at startup if secret-file encryption is not configured.
+	// Placed after one-shot flag handlers so it doesn't pollute their
+	// stdout output (e.g. --show-api-key piped to a clipboard tool).
+	if ok, _ := crypto.EncryptionConfigured(); !ok {
+		logger.Warn("Secret files are stored in plaintext. " +
+			"Set GEARBOX_AGENT_ENCRYPTION_KEY (64 hex chars, see 'openssl rand -hex 32') " +
+			"to enable AES-256-GCM encryption-at-rest.")
+	}
+
 	// Load or create API key
 	apiKey, isNewKey, err := crypto.LoadOrCreateAPIKey(cfg.APIKeyPath)
 	if err != nil {

gearbox-agent/internal/framework/crypto/aead.go

@@ -17,9 +17,14 @@ var magic = [4]byte{'G', 'B', 'E', '1'}
 
 // ErrKeyRequired is returned when an encrypted file is found but no encryption key
 // has been configured. Key loss means rotation — there is no recovery path.
+//
+// Recovery: set GEARBOX_AGENT_ENCRYPTION_KEY to the correct value to decrypt;
+// or delete the file and re-generate (--rotate-api-key for the API key,
+// --generate-webhook-secret for the webhook secret — note the latter does
+// NOT overwrite an existing file, so you must rm it first).
 var ErrKeyRequired = errors.New(
 	"secret file is encrypted (GBE1) but GEARBOX_AGENT_ENCRYPTION_KEY is not set; " +
-		"set the key to decrypt, or rotate the secret (--rotate-api-key / --generate-webhook-secret)",
+		"set the key to decrypt, or delete the file and re-generate the secret",
 )
 
 // KeyProvider supplies the 32-byte AES-256 key used to protect on-disk secrets.
@@ -33,7 +38,8 @@ type KeyProvider interface {
 }
 
 // EnvKeyProvider reads the encryption key from an environment variable.
-// The variable must contain exactly 64 lowercase hex characters (32 bytes / 256 bits).
+// The variable must contain exactly 64 hex characters (32 bytes / 256 bits);
+// both upper- and lower-case hex are accepted.
 // Generate a suitable value with: openssl rand -hex 32
 type EnvKeyProvider struct {
 	EnvVar string // environment variable name; default "GEARBOX_AGENT_ENCRYPTION_KEY"