feat: add codexbar guard — quota-aware exit code to gate automation

Sources/CodexBarCLI/CLIConfigCommand.swift

@@ -3,6 +3,29 @@ import Commander
 import Foundation
 
 extension CodexBarCLI {
+    static func runConfig(path: [String], values: ParsedValues) {
+        switch path {
+        case ["config", "validate"]:
+            self.runConfigValidate(values)
+        case ["config", "dump"]:
+            self.runConfigDump(values)
+        case ["config", "providers"]:
+            self.runConfigProviders(values)
+        case ["config", "enable"]:
+            self.runConfigSetProviderEnabled(values, enabled: true)
+        case ["config", "disable"]:
+            self.runConfigSetProviderEnabled(values, enabled: false)
+        case ["config", "set-api-key"]:
+            self.runConfigSetAPIKey(values)
+        default:
+            self.exit(
+                code: .failure,
+                message: "Unknown command",
+                output: CLIOutputPreferences.from(values: values),
+                kind: .args)
+        }
+    }
+
     static func runConfigValidate(_ values: ParsedValues) {
         let output = CLIOutputPreferences.from(values: values)
         let config = Self.loadConfig(output: output)

Sources/CodexBarCLI/CLIEntry.swift

@@ -59,18 +59,8 @@ enum CodexBarCLI {
                 await self.runSessionsFocus(invocation.parsedValues)
             case ["serve"]:
                 await self.runServe(invocation.parsedValues)
-            case ["config", "validate"]:
-                self.runConfigValidate(invocation.parsedValues)
-            case ["config", "dump"]:
-                self.runConfigDump(invocation.parsedValues)
-            case ["config", "providers"]:
-                self.runConfigProviders(invocation.parsedValues)
-            case ["config", "enable"]:
-                self.runConfigSetProviderEnabled(invocation.parsedValues, enabled: true)
-            case ["config", "disable"]:
-                self.runConfigSetProviderEnabled(invocation.parsedValues, enabled: false)
-            case ["config", "set-api-key"]:
-                self.runConfigSetAPIKey(invocation.parsedValues)
+            case let path where path.first == "config":
+                self.runConfig(path: path, values: invocation.parsedValues)
             case let path where path.first == "hooks":
                 await self.runHooks(path: path, values: invocation.parsedValues)
             case ["cache", "clear"]:
@@ -81,6 +71,8 @@ enum CodexBarCLI {
                 }
                 defer { signalMonitor.cancel() }
                 await self.runDiagnose(invocation.parsedValues)
+            case ["guard"]:
+                await self.runGuard(invocation.parsedValues)
             default:
                 Self.exit(
                     code: .failure,
@@ -89,7 +81,8 @@ enum CodexBarCLI {
                     kind: .args)
             }
         } catch let error as CommanderProgramError {
-            Self.exit(code: .failure, message: error.description, output: outputPreferences, kind: .args)
+            let exitCode: ExitCode = argv.first == "guard" ? .usage : .failure
+            Self.exit(code: exitCode, message: error.description, output: outputPreferences, kind: .args)
         } catch {
             Self.exit(code: .failure, message: error.localizedDescription, output: outputPreferences, kind: .runtime)
         }
@@ -109,6 +102,7 @@ enum CodexBarCLI {
         let diagnoseSignature = CommandSignature.describe(DiagnoseOptions())
         let hooksSignature = CommandSignature.describe(HooksOptions())
         let hooksTestSignature = CommandSignature.describe(HooksTestOptions())
+        let guardSignature = CommandSignature.describe(GuardOptions())
 
         return [
             CommandDescriptor(
@@ -121,6 +115,11 @@ enum CodexBarCLI {
                 abstract: "Print usage as text or JSON",
                 discussion: nil,
                 signature: usageSignature),
+            CommandDescriptor(
+                name: "guard",
+                abstract: "Exit non-zero when a provider lacks quota headroom (for gating scripts)",
+                discussion: nil,
+                signature: guardSignature),
             CommandDescriptor(
                 name: "cost",
                 abstract: "Print local cost usage as text or JSON",

Sources/CodexBarCLI/CLIExitCode.swift

@@ -4,6 +4,7 @@ enum ExitCode: Int32 {
     case binaryNotFound = 2
     case parseError = 3
     case timeout = 4
+    case usage = 64
 
     init(_ rawValue: Int) {
         self = ExitCode(rawValue: Int32(rawValue)) ?? .failure