feat: cockatiel resilience, security hardening, and error classification

.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -E \"\\\\.ts$|\\\\.js$|\\\\.json$\")",
+      "Bash(xargs wc:*)",
+      "Bash(bun test:*)",
+      "Bash(bun run:*)"
+    ]
+  }
+}

.github/workflows/ci.yml

@@ -1,6 +1,8 @@
 name: CI
 
 on:
+  push:
+    branches: [master]
   pull_request:
     branches: [develop, master]
 

.github/workflows/release.yml

@@ -12,6 +12,7 @@ on:
 
 permissions:
   contents: write
+  id-token: write
 
 jobs:
   test:
@@ -41,6 +42,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -49,14 +52,25 @@ jobs:
           node-version: "22"
           registry-url: "https://registry.npmjs.org"
       - run: bun install
+      - name: Determine version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TAG="${{ inputs.tag }}"
+          else
+            PKG_VERSION=$(node -p "require('./package.json').version")
+            TAG="v${PKG_VERSION}"
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          npm version "${TAG#v}" --no-git-tag-version --allow-same-version
       - name: Publish to npm
-        run: npm publish --access public
+        run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       - name: Create tag and release
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          TAG="v$(node -p "require('./package.json').version")"
+          TAG="${{ steps.version.outputs.tag }}"
           git tag "$TAG" 2>/dev/null && git push origin "$TAG" || echo "Tag exists"
           gh release create "$TAG" --title "$TAG" --generate-notes || echo "Release exists"

package.json

@@ -18,6 +18,9 @@
   ],
   "author": "lleontor705",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/lleontor705/opencode-cli-enforcer.git"
@@ -29,12 +32,16 @@
   ],
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.26",
+    "cockatiel": "^3.2.1",
     "execa": "^9.6.1"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.7.0"
   },
+  "engines": {
+    "bun": ">=1.3.5"
+  },
   "scripts": {
     "test": "bun test",
     "test:watch": "bun test --watch",

src/error-classifier.ts

@@ -0,0 +1,38 @@
+/**
+ * Error Classification — determines retry strategy based on error type.
+ *
+ * Categories:
+ *   transient  → retry with standard backoff
+ *   rate_limit → retry with longer delay
+ *   permanent  → do not retry, fallback immediately
+ *   crash      → do not retry, fallback immediately
+ */
+
+export type ErrorClass = "transient" | "rate_limit" | "permanent" | "crash"
+
+export function classifyError(error: any): ErrorClass {
+  const msg = String(error?.message || error?.stderr || "")
+
+  // Crash: process killed, binary not found
+  if (error?.exitCode === 137 || msg.includes("SIGKILL") || msg.includes("ENOENT")) {
+    return "crash"
+  }
+
+  // Rate limit: HTTP 429 or quota errors
+  if (msg.includes("429") || msg.includes("rate limit") || msg.includes("quota")) {
+    return "rate_limit"
+  }
+
+  // Permanent: auth failures, not found
+  if (
+    msg.includes("auth") ||
+    msg.includes("401") ||
+    msg.includes("403") ||
+    msg.includes("not found")
+  ) {
+    return "permanent"
+  }
+
+  // Everything else is transient (timeout, network, etc.)
+  return "transient"
+}

src/executor.ts

@@ -4,6 +4,8 @@
 
 import { execa } from "execa"
 import type { CliDef } from "./cli-defs"
+import { getSafeEnv } from "./safe-env"
+import { redactSecrets } from "./redact"
 
 /** Prompts longer than this (chars) are delivered via stdin to avoid OS arg-length limits. */
 export const STDIN_THRESHOLD = 30_000
@@ -30,6 +32,7 @@ export async function executeCliOnce(
     maxBuffer: 10 * 1024 * 1024,
     reject: false,
     windowsHide: true,
+    env: getSafeEnv(),
     ...(useStdin ? { input: prompt } : {}),
     ...(signal ? { cancelSignal: signal } : {}),
   })
@@ -47,8 +50,11 @@ export async function executeCliOnce(
   }
 
   if (result.failed && result.exitCode !== 0) {
-    const msg = result.stderr?.trim() || result.message || `Exit code ${result.exitCode}`
-    throw new Error(`CLI '${def.name}' failed: ${msg}`)
+    const rawMsg = result.stderr?.trim() || result.message || `Exit code ${result.exitCode}`
+    const msg = redactSecrets(rawMsg)
+    throw Object.assign(new Error(`CLI '${def.name}' failed: ${msg}`), {
+      exitCode: result.exitCode,
+    })
   }
 
   return {

src/index.ts

@@ -24,6 +24,7 @@ import { DEFAULT_RETRY_CONFIG } from "./retry"
 import { detectAllClis, type CliAvailability } from "./detection"
 import { truncate } from "./executor"
 import { executeWithResilience, type ResilienceContext, type UsageStats } from "./resilience"
+import { redactSecrets } from "./redact"
 
 // Agents that should NOT receive CLI injection
 const NO_CLI_AGENTS = new Set(["orchestrator", "task_decomposer"])
@@ -141,7 +142,8 @@ Rules: One concern per call. Split large requests. Include "CLI Consultations" i
           return {
             ...response,
             stdout: truncate(response.stdout, 50_000),
-            stderr: truncate(response.stderr, 5_000),
+            stderr: redactSecrets(truncate(response.stderr, 5_000)),
+            error: response.error ? redactSecrets(response.error) : null,
           }
         },
       }),

src/policies.ts

@@ -0,0 +1,48 @@
+/**
+ * Cockatiel Resilience Policies — composable retry, circuit breaker,
+ * bulkhead, and timeout policies using cockatiel.
+ *
+ * Composition order (outermost → innermost):
+ *   timeout → retry → circuit breaker → bulkhead
+ */
+
+import {
+  CircuitBreakerPolicy,
+  ConsecutiveBreaker,
+  retry,
+  handleAll,
+  wrap,
+  bulkhead,
+  timeout,
+  ExponentialBackoff,
+  type IPolicy,
+} from "cockatiel"
+
+/** Per-CLI bulkhead: max 2 concurrent, queue up to 3 */
+export const cliBulkhead = bulkhead(2, 3)
+
+/** Circuit breaker: open after 3 consecutive failures, half-open after 30s */
+export const circuitBreaker = new CircuitBreakerPolicy(handleAll, {
+  halfOpenAfter: 30_000,
+  breaker: new ConsecutiveBreaker(3),
+})
+
+/** Retry with decorrelated jitter (AWS best practice) */
+export const retryPolicy = retry(handleAll, {
+  maxAttempts: 3,
+  backoff: new ExponentialBackoff({ initialDelay: 1000, maxDelay: 30000 }),
+})
+
+/** Default timeout: 30 seconds */
+export const timeoutPolicy = timeout(30_000)
+
+/**
+ * Composed resilient policy: timeout → retry → circuit breaker → bulkhead.
+ * Wrap calls with `resilientPolicy.execute(fn)`.
+ */
+export const resilientPolicy: IPolicy = wrap(
+  timeoutPolicy,
+  retryPolicy,
+  circuitBreaker,
+  cliBulkhead,
+)

src/redact.ts

@@ -0,0 +1,10 @@
+/**
+ * Secret Redaction — removes API keys and tokens from text before
+ * returning it to the user in error messages or logs.
+ */
+
+export function redactSecrets(text: string): string {
+  return text
+    .replace(/(?:sk-|key-|AIza|ant-api)[a-zA-Z0-9_-]{20,}/g, "[REDACTED]")
+    .replace(/Bearer\s+[a-zA-Z0-9._-]+/g, "Bearer [REDACTED]")
+}

src/resilience.ts

@@ -13,11 +13,13 @@ import {
   recordFailure,
 } from "./circuit-breaker"
 import type { RetryConfig } from "./retry"
-import { DEFAULT_RETRY_CONFIG, calculateDelay, sleep, isRetryableError } from "./retry"
+import { DEFAULT_RETRY_CONFIG, calculateDelay, sleep } from "./retry"
 import { executeCliOnce } from "./executor"
 import type { CliAvailability } from "./detection"
 import type { Platform } from "./platform"
 import type { CircuitState } from "./circuit-breaker"
+import { classifyError, type ErrorClass } from "./error-classifier"
+import { redactSecrets } from "./redact"
 
 // ─── Structured Response (MCP pattern) ─────────────────────────────────────
 
@@ -32,6 +34,7 @@ export interface CliResponse {
   used_fallback: boolean
   fallback_chain: string[]
   error: string | null
+  error_class: ErrorClass | null
   circuit_state: CircuitState
   attempt: number
   max_attempts: number
@@ -128,21 +131,37 @@ export async function executeWithResilience(
           used_fallback: cliName !== targetCli,
           fallback_chain: fallbackChain,
           error: null,
+          error_class: null,
           circuit_state: breaker.state,
           attempt: attempt + 1,
           max_attempts: ctx.retryConfig.maxRetries + 1,
         }
       } catch (err: unknown) {
         stats.failures++
 
-        const retryable = isRetryableError(err)
-        const isLastAttempt = attempt === ctx.retryConfig.maxRetries
+        const errorClass = classifyError(err)
+
+        // permanent and crash errors: skip retries, fallback immediately
+        if (errorClass === "permanent" || errorClass === "crash") {
+          recordFailure(breaker, ctx.breakerConfig)
+          break // try next CLI in fallback chain
+        }
+
+        // rate_limit: wait longer before retrying
+        if (errorClass === "rate_limit") {
+          const rateLimitDelay = calculateDelay(attempt + 1, {
+            ...ctx.retryConfig,
+            baseDelayMs: ctx.retryConfig.baseDelayMs * 3,
+          })
+          await sleep(rateLimitDelay)
+        }
 
-        if (!retryable || isLastAttempt) {
+        const isLastAttempt = attempt === ctx.retryConfig.maxRetries
+        if (isLastAttempt) {
           recordFailure(breaker, ctx.breakerConfig)
           break // try next CLI in fallback chain
         }
-        // retryable — loop continues
+        // transient or rate_limit — loop continues with retry
       }
     }
   }
@@ -158,7 +177,10 @@ export async function executeWithResilience(
     timed_out: false,
     used_fallback: fallbackChain.length > 1,
     fallback_chain: fallbackChain,
-    error: `All CLI providers exhausted. Tried: ${fallbackChain.join(" → ")}. Check cli_status for details.`,
+    error: redactSecrets(
+      `All CLI providers exhausted. Tried: ${fallbackChain.join(" → ")}. Check cli_status for details.`,
+    ),
+    error_class: "transient",
     circuit_state: ctx.breakers.get(targetCli)!.state,
     attempt: ctx.retryConfig.maxRetries + 1,
     max_attempts: ctx.retryConfig.maxRetries + 1,

src/safe-env.ts

@@ -0,0 +1,30 @@
+/**
+ * Environment Variable Filtering — only passes safe variables to
+ * spawned CLI processes, preventing accidental secret leakage.
+ */
+
+export const SAFE_ENV_VARS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "TERM",
+  "SHELL",
+  "LANG",
+  "LC_ALL",
+  "ANTHROPIC_API_KEY",
+  "GOOGLE_API_KEY",
+  "OPENAI_API_KEY",
+  "GEMINI_API_KEY",
+  "CODEX_API_KEY",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+]
+
+export function getSafeEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const key of SAFE_ENV_VARS) {
+    if (process.env[key]) env[key] = process.env[key]!
+  }
+  return env
+}