jules-orchestrator-kit 0.24.0 → 1.0.1

package/README.md

@@ -1,24 +1,33 @@
-# jules-orchestrator-kit
+<div align="center">
 
-*Disclaimer: This is an independent open-source orchestration tool for Google Jules and is not officially affiliated with or endorsed by Google.*
+# 🚀 jules-orchestrator-kit
+
+### High-Volume Autonomous AI Agent Orchestration Engine for Google Jules
 
 [![Jules PR Audit](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml/badge.svg)](https://github.com/FullThrottle83/jules-orchestrator-kit/actions/workflows/jules-audit.yml)
 [![npm version](https://img.shields.io/npm/v/jules-orchestrator-kit.svg)](https://www.npmjs.com/package/jules-orchestrator-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20native-blue.svg)](https://nodejs.org)
+
+<p align="center">
+  <b>Zero-dependency safety kernel and high-throughput orchestration engine for autonomous AI agent swarms.</b><br/>
+  Built specifically to execute 300+ daily agent sessions and parallel worktree swarms safely on native Node.js 20+ ESM.
+</p>
 
-> **High-Volume Autonomous Orchestration Engine for Google Jules**  
-> Built specifically to execute 300+ daily agent sessions and parallel swarms safely. Zero external runtime dependencies. Built strictly on native Node.js 20+ ESM.
+</div>
 
 ---
 
-![Autonomous Orchestration Pipeline](docs/assets/hero-flow.svg?v=3)
+<p align="center">
+  <img src="docs/assets/hero-flow.svg?v=3" alt="Autonomous Orchestration Pipeline" width="100%" />
+</p>
 
 ---
 
 ## ⚡ 2-Minute Quickstart
 
-Get up and running in under 2 minutes with zero complex configuration:
+> 💡 **TIP**: **New to Google Jules or agent automation?** You don't need any complex setup! `jules-orchestrator-kit` works out of the box with standard `npm test` and zero external dependencies.
 
 ```bash
 # 1. Initialize orchestrator structure in your target codebase
@@ -36,7 +45,7 @@ npx agentctl gate
 npx agentctl mcp
 ```
 
-> 📖 **Looking for production deployment patterns?**  
+> 📖 **NOTE**: **Looking for production deployment patterns?**  
 > Check out [**EXAMPLES.md**](./EXAMPLES.md) for 6 real-world recipes (Nightly TODO Scanner, Composite CI Action, Multi-Worktree Swarms, OODA Auto-Fix, MCP IDE setup, and Specialist Rosters).
 
 ---
@@ -55,17 +64,19 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 ---
 
+## 🏛️ System Architecture & Visual Diagrams
+
 <details open>
-<summary><b>⚙️ Control Plane Architecture & Deep Dive</b></summary>
+<summary><b>📐 1. Control Plane Architecture Layers</b></summary>
 
 <br/>
 
-![Control Plane Architecture Layers](docs/assets/architecture-layers.svg?v=3)
+<p align="center">
+  <img src="docs/assets/architecture-layers.svg?v=3" alt="Control Plane Architecture Layers" width="100%" />
+</p>
 
 <br/>
 
-![Self-Healing OODA Loop](docs/assets/ooda-loop-cycle.svg?v=3)
-
 ### Engine System Highlights
 
 - **Native Task DAG Executor (`src/dag-engine.mjs`)**: Zero-dependency `DagExecutor` with Kahn's topological sort algorithm, SHA-256 interface fingerprinting post-task execution, and pre-execution cycle detection (`DagCycleError`).
@@ -80,12 +91,31 @@ Whether you are dispatching your first automated coding task or managing high-th
 
 </details>
 
-<details>
-<summary><b>🛡️ Zero-Trust Security Gatekeeper</b></summary>
+<details open>
+<summary><b>🔁 2. Self-Healing OODA Loop Cycle</b></summary>
 
 <br/>
 
-![Zero-Trust Security Guarantees](docs/assets/security-shield.svg?v=3)
+<p align="center">
+  <img src="docs/assets/ooda-loop-cycle.svg?v=3" alt="Self-Healing OODA Loop" width="100%" />
+</p>
+
+<br/>
+
+> 🚨 **IMPORTANT**: The OODA (Observe-Orient-Decide-Act) loop executes up to 3 repair attempts when tests fail. If the failure output oscillates deterministically without progress, the OODA engine halts repair to save API tokens and returns Exit Code 4.
+
+</details>
+
+<details open>
+<summary><b>🛡️ 3. Zero-Trust Security Shield & 4-Phase Gate</b></summary>
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/security-shield.svg?v=3" alt="Zero-Trust Security Guarantees" width="100%" />
+</p>
+
+<br/>
 
 ### The 4-Phase Safety Audit & Security Boundary (`agentctl gate`)
 
@@ -96,17 +126,35 @@ Whether you are dispatching your first automated coding task or managing high-th
 5. **Prompt Guard Boundary (`src/prompt-guard.mjs`)**: `sanitizeUntrustedData` strips bidi control characters, ANSI escape sequences, zero-width unicode, and neutralizes prompt injection tags (`<|im_start|>`, `[INST]`).
 6. **MCP Stream Isolation (`src/mcp.mjs`)**: Seals `process.stdout.write` framing stream to prevent log output from corrupting JSON-RPC stdio frames.
 
-> [!NOTE]
-> All security rules are fetched strictly from `origin/main` (never untrusted PR branches) to prevent prompt-injection attacks from altering security rules.
+> ⚠️ **WARNING**: All security rules are fetched strictly from `origin/main` (never untrusted PR branches) to prevent prompt-injection attacks from altering security rules.
 
 </details>
 
-<details>
-<summary><b>🔌 Model Context Protocol (MCP) & IDE Integration</b></summary>
+<details open>
+<summary><b>🐝 4. Parallel Swarm Topology & Isolated Worktrees</b></summary>
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/swarm-topology.svg?v=3" alt="Multi-Agent Swarm Topology" width="100%" />
+</p>
 
 <br/>
 
-![Dual-Way MCP Integration](docs/assets/mcp-integration.svg?v=3)
+> 📌 **NOTE**: Swarm execution spawns dedicated git worktrees for each task in parallel, isolated by VFS locks. Completed tasks are verified and merged back using 3-way AST/JSON structural merging (`agentctl swarm`).
+
+</details>
+
+<details open>
+<summary><b>🔌 5. Model Context Protocol (MCP) & IDE Integration</b></summary>
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/mcp-integration.svg?v=3" alt="Dual-Way MCP Integration" width="100%" />
+</p>
+
+<br/>
 
 ### Connecting to Claude Desktop, Cursor, or Antigravity
 
@@ -121,15 +169,40 @@ npx agentctl mcp
 - `audit_jules_gate`: Execute the 4-phase safety gate against the workspace.
 - `check_risk_tier`: Classify workspace changes into Risk Tiers (R0 Cosmetic to R3 Restricted).
 - `get_jules_status`: Fetch real-time status of active, pending, and completed tasks.
+- `telemetry_tail`: Query last N real-time telemetry events from the SHA-256 hash spine.
 
 </details>
 
-<details>
-<summary><b>🤖 Specialist Agent Prompt Presets (.agent/prompts/)</b></summary>
+<details open>
+<summary><b>💳 6. Subscription Tier Presets Matrix</b></summary>
+
+<br/>
+
+<p align="center">
+  <img src="docs/assets/tier-presets.svg?v=3" alt="Subscription Tier Presets Matrix" width="100%" />
+</p>
 
 <br/>
 
-Specialized prompt presets enforcement payload limits (< 75 KB) and domain guardrails out of the box:
+Tailor session limits and rate-limiting behavior to your Google Jules API subscription tier:
+
+| Tier | `dailyTasks` | `repairAttempts` | `concurrency` | `staggerMs` | Target Usage |
+| :--- | :---: | :---: | :---: | :---: | :--- |
+| **`free`** | `15` | `1` | `1` | `3000 ms` | **Hobby / Free Tier:** Conserves quota, prevents HTTP 429 rate limits. |
+| **`pro`** | `100` | `2` | `2` | `1500 ms` | **Developer Pro:** Balanced throughput for everyday work. |
+| **`ultra`** *(default)* | `300` | `3` | `3` | `1000 ms` | **Swarm / Enterprise:** Maximum parallel throughput & CI/CD. |
+
+**How to activate:**
+- **Environment Variable:** `export JULES_TIER=free` (or set in `.env`)
+- **Config File (`.agent/jules.yml`):** Set `tier: free`
+
+</details>
+
+---
+
+## 🤖 Specialist Agent Prompt Presets (`.agent/prompts/`)
+
+Specialized prompt presets enforce payload limits (< 75 KB) and domain guardrails out of the box:
 
 | Preset | Role & Domain | Primary Focus |
 | :--- | :--- | :--- |
@@ -144,12 +217,9 @@ npx agentctl dispatch \
   --prompt "$(cat .agent/prompts/Janitor.md) Prune unused helper methods in src/utils.mjs"
 ```
 
-</details>
-
-<details>
-<summary><b>⚡ GitHub Actions Composite Action (.github/actions/setup-jules)</b></summary>
+---
 
-<br/>
+## ⚡ GitHub Actions Composite Action (`.github/actions/setup-jules`)
 
 Integrate `jules-orchestrator-kit` into any GitHub Actions workflow with 3 lines of YAML:
 
@@ -165,12 +235,9 @@ steps:
       JULES_API_KEY: ${{ secrets.JULES_API_KEY }}
 ```
 
-</details>
-
-<details>
-<summary><b>🛠️ CLI Command Reference (`agentctl`)</b></summary>
+---
 
-<br/>
+## 🛠️ CLI Command Reference (`agentctl`)
 
 | Command | Usage Example | Description |
 | :--- | :--- | :--- |
@@ -185,35 +252,9 @@ steps:
 | **`scan`** | `agentctl scan` | Scans codebase for `TODO` and `FIXME` comments and generates task queue |
 | **`clean`** | `agentctl clean` | Audits and cleans up stale git worktrees, orphaned intents, locks, and temporary state files |
 
-</details>
-
-<details>
-<summary><b>💳 Subscription Tier Presets (Free / Pro / Ultra)</b></summary>
-
-<br/>
-
-![Subscription Tier Presets Matrix](docs/assets/tier-presets.svg?v=3)
-
-<br/>
-
-Tailor session limits and rate-limiting behavior to your Google Jules API subscription tier:
-
-| Tier | `dailyTasks` | `repairAttempts` | `concurrency` | `staggerMs` | Target Usage |
-| :--- | :---: | :---: | :---: | :---: | :--- |
-| **`free`** | `15` | `1` | `1` | `3000 ms` | **Hobby / Free Tier:** Conserves quota, prevents HTTP 429 rate limits. |
-| **`pro`** | `100` | `2` | `2` | `1500 ms` | **Developer Pro:** Balanced throughput for everyday work. |
-| **`ultra`** *(default)* | `300` | `3` | `3` | `1000 ms` | **Swarm / Enterprise:** Maximum parallel throughput & CI/CD. |
-
-**How to activate:**
-- **Environment Variable:** `export JULES_TIER=free` (or set in `.env`)
-- **Config File (`.agent/jules.yml`):** Set `tier: free`
-
-</details>
-
-<details>
-<summary><b>📝 Configuration Reference (`.agent/jules.yml`)</b></summary>
+---
 
-<br/>
+## 📝 Configuration Reference (`.agent/jules.yml`)
 
 Auto-generated by `agentctl init` at the root of your project:
 
@@ -233,16 +274,13 @@ limits:
   diffKb: 75
 ```
 
-</details>
-
-<details>
-<summary><b>🚦 Exit Code Registry & Troubleshooting</b></summary>
+---
 
-<br/>
+## 🚦 Exit Code Registry & Troubleshooting
 
-Standardized exit codes enforced across all CLI utilities:
+Standardized exit codes enforced across all CLI utilities and CI pipelines:
 
-| Exit Code | Status | Description & Immediate Action |
+| Exit Code | Classification | Description & Immediate Remediation Action |
 | :---: | :--- | :--- |
 | `0` | **Success** | Task completed cleanly; PR opened or verification passed. |
 | `1` | **Pre-Dispatch / Arg Error** | Invalid arguments, prompt > 50 KB, or pre-dispatch validation error. |
@@ -250,15 +288,15 @@ Standardized exit codes enforced across all CLI utilities:
 | `3` | **Scope Violation** | Attempted modification of restricted files (`.github/`, command files, agent rules). |
 | `4` | **OODA Exhausted / Thrash** | Verification suite failed after 3 repair attempts or hit deterministic regression. |
 | `5` | **Diff Payload Limit** | Post-change git diff exceeds payload budget (`limits.diffKb`, default 75 KB). |
-| `6` | **Secret Detected** | High-confidence secret or private key detected in patch diff. |
+| `6` | **Secret Detected** | High-confidence secret or private key detected in patch diff (Shannon entropy > 3.6 bits). |
 | `7` | **Budget Exhausted** | Daily task session quota limit reached (`limits.dailyTasks`, default 300). |
+| `8` | **FLAKY_QUARANTINE** | Statistical test flakiness detected (oscillation >= 0.4, Wilson CI); OODA repair suppressed. |
+| `124` | **Execution Timeout** | Subprocess execution exceeded hard timeout limit (default 10 minutes). |
+| `188` | **ERR_UNMOCKED_NET** | Unmocked outbound HTTP/HTTPS egress intercepted by hermetic network guard. |
 
-</details>
-
-<details>
-<summary><b>🔐 Environment Variables Reference</b></summary>
+---
 
-<br/>
+## 🔐 Environment Variables Reference
 
 | Variable | Description | Default |
 | :--- | :--- | :--- |
@@ -273,12 +311,9 @@ Standardized exit codes enforced across all CLI utilities:
 | `BASE_BRANCH` | Base branch for PR Audits & Merge-Base checks | `main` |
 | `NO_COLOR` | Set to `true` to disable ANSI color output | `false` |
 
-</details>
-
-<details>
-<summary><b>🌐 Supported Tech Stacks & Auto-Detection</b></summary>
+---
 
-<br/>
+## 🌐 Supported Tech Stacks & Auto-Detection
 
 The orchestrator automatically infers verification and build commands across ecosystems:
 
@@ -295,8 +330,6 @@ The orchestrator automatically infers verification and build commands across eco
 | **Elixir / Ruby** | `mix.exs` / `Gemfile` | `mix test` / `rake test` | *(standard build)* |
 | **Java / C / C++** | `pom.xml` / `Makefile` | `mvn test` / `make test` | `mvn compile` / `make` |
 
-</details>
-
 ---
 
 ## 🤝 Contributing & Standards

package/bin/agentctl.mjs

@@ -14,7 +14,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.24.0 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v1.0.1 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 
@@ -44,7 +44,7 @@ async function main() {
   }
 
   if (command === "version" || command === "--version" || command === "-v") {
-    console.log("agentctl v0.24.0");
+    console.log("agentctl v1.0.1");
     process.exit(0);
   }
 
@@ -226,7 +226,7 @@ async function main() {
     }
 
     case "doctor": {
-      console.log(`\n🔍 agentctl System Diagnostics (v0.24.0)`);
+      console.log(`\n🔍 agentctl System Diagnostics (v1.0.1)`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);

package/index.mjs

@@ -1,5 +1,5 @@
 /**
- * Google Jules Orchestrator Kit - Node.js SDK (v0.24.0)
+ * Google Jules Orchestrator Kit - Node.js SDK (v1.0.1)
  *
  * Exposes core orchestrator functions for programmatically driving agent tasks,
  * security auditing, repo gating, and state operations.
@@ -17,7 +17,16 @@ export {
 export { sanitizeUntrustedData, buildAgentEnvelope } from "./src/prompt-guard.mjs";
 export { isolateMcpStdout, writeMcpFrame } from "./src/mcp.mjs";
 export { git, runCmd, resolveBase, changedFiles, diffBytes, diffText } from "./src/git.mjs";
-export { createProvider, JULES_PRESET, CLAUDE_PRESET, CODEX_PRESET } from "./src/provider.mjs";
+export {
+  createProvider,
+  JULES_PRESET,
+  CLAUDE_PRESET,
+  CODEX_PRESET,
+  ProviderRateLimitError,
+  ProviderUnavailableError,
+  ProviderSchemaError,
+  parseRetryAfter,
+} from "./src/provider.mjs";
 export {
   appendLedger,
   readLedger,
@@ -25,6 +34,7 @@ export {
   reserveBudget,
   reserveBudgetAtomic,
   commitBudgetReservation,
+  rollbackBudgetReservation,
   withBudget,
   checkDailyBudget,
   acquireLock,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.24.0",
+  "version": "1.0.1",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",
@@ -23,20 +23,16 @@
     ".": "./index.mjs"
   },
   "files": [
-    "index.mjs",
-    "src/",
     "bin/",
+    "src/",
     "scripts/",
-    ".agent/jules.yml",
+    "index.mjs",
+    "LICENSE",
+    "README.md",
+    "JULES_RULES_TEMPLATE.md",
     ".agent/rules/",
     ".agent/prompts/",
-    ".agent/workflows/",
-    ".agent/jules-queue/README.md",
-    ".github/workflows/jules-audit.yml",
-    ".env.example",
-    "JULES_RULES_TEMPLATE.md",
-    "README.md",
-    "LICENSE"
+    ".agent/workflows/"
   ],
   "scripts": {
     "init": "node bin/init.js",

package/src/engine.mjs

@@ -1,8 +1,8 @@
 import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
 import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
 import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
-import { createProvider } from "./provider.mjs";
-import { withBudget, appendLedger, getQueueDir, ensureDir } from "./state.mjs";
+import { createProvider, ProviderRateLimitError, ProviderUnavailableError } from "./provider.mjs";
+import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation } from "./state.mjs";
 import { sanitizeUntrustedData, buildAgentEnvelope } from "./prompt-guard.mjs";
 import { recordVerifyRun, readVerifyRuns, flakyVerdict } from "./flaky-ledger.mjs";
 import { readdirSync, readFileSync, renameSync, existsSync } from "node:fs";
@@ -346,6 +346,24 @@ export async function repair(failure, opts = {}) {
         config.limits.dailyTasks
       );
     } catch (err) {
+      if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
+        if (err.reservationId) {
+          rollbackBudgetReservation(root, err.reservationId);
+        }
+        const retryAfterMs = err.retryAfterMs || 60000;
+        const backoffSec = Math.ceil(retryAfterMs / 1000);
+        console.warn(`[PROVIDER_INFRASTRUCTURE_FAILURE] ${err.name}: ${err.message}. Recommended backoff: ${backoffSec}s.`);
+        attempts.push({ n, ok: false, error: err.message, providerError: true, retryAfterMs });
+        appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: false, error: err.message, providerError: true });
+        return {
+          ok: false,
+          attempts,
+          finalStatus: "PROVIDER_INFRASTRUCTURE_FAILURE",
+          error: err.message,
+          retryAfterMs,
+          providerError: true,
+        };
+      }
       attempts.push({ n, ok: false, error: err.message });
       appendTelemetry(root, "ooda_repair_attempt", { attempt: n, ok: false, error: err.message });
       break;
@@ -482,11 +500,31 @@ export async function dispatch(task, opts = {}) {
 
   const cleanTask = { ...task, prompt: envelopedPrompt };
 
-  return withBudget(
-    () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun }),
-    root,
-    config.limits.dailyTasks
-  );
+  try {
+    return await withBudget(
+      () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun }),
+      root,
+      config.limits.dailyTasks
+    );
+  } catch (err) {
+    if (err instanceof ProviderRateLimitError || err instanceof ProviderUnavailableError) {
+      if (err.reservationId) {
+        rollbackBudgetReservation(root, err.reservationId);
+      }
+      const retryAfterMs = err.retryAfterMs || 60000;
+      const status = err instanceof ProviderRateLimitError ? "RATE_LIMITED" : "PROVIDER_UNAVAILABLE";
+      const backoffSec = Math.ceil(retryAfterMs / 1000);
+      console.warn(`[PROVIDER_INFRASTRUCTURE_FAILURE] ${err.name}: ${err.message}. Recommended backoff: ${backoffSec}s.`);
+      return {
+        ok: false,
+        status,
+        error: err.message,
+        retryAfterMs,
+        providerError: true,
+      };
+    }
+    throw err;
+  }
 }
 
 export async function run(tasksOrOpts = {}, opts = {}) {

package/src/mcp.mjs

@@ -9,7 +9,7 @@ import { ProgressBus } from "./mcp-progress.mjs";
 
 export const MCP_SERVER_INFO = {
   name: "jules-orchestrator-kit",
-  version: "0.23.0",
+  version: "1.0.1",
 };
 
 export const MAX_MCP_FRAME_SIZE = 4 * 1024 * 1024; // 4 MB memory safety ceiling

package/src/provider.mjs

@@ -31,6 +31,45 @@ export const CODEX_PRESET = {
   promptViaStdin: false,
 };
 
+export class ProviderRateLimitError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "ProviderRateLimitError";
+    this.retryAfterMs = opts.retryAfterMs ?? 60000;
+    this.status = opts.status || 429;
+  }
+}
+
+export class ProviderUnavailableError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "ProviderUnavailableError";
+    this.status = opts.status || 503;
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+}
+
+export class ProviderSchemaError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "ProviderSchemaError";
+    this.status = opts.status;
+  }
+}
+
+export function parseRetryAfter(header) {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (!isNaN(seconds)) {
+    return Math.max(0, Math.round(seconds * 1000));
+  }
+  const dateMs = Date.parse(header);
+  if (!isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return null;
+}
+
 function interpolateString(template, data) {
   if (typeof template !== "string") return template;
   return template.replace(/\{(\w+)\}/g, (_, key) => data[key] ?? "");
@@ -111,20 +150,63 @@ export function createProvider(spec = "jules", config = {}) {
           body = JSON.stringify(data);
         }
 
-        const res = await fetch(url, {
-          method: providerSpec.method || "POST",
-          headers,
-          body,
-        });
+        const timeoutMs = ctx.timeoutMs || config.timeoutMs || providerSpec.timeoutMs || 120_000;
+        let res;
+        try {
+          res = await fetch(url, {
+            method: providerSpec.method || "POST",
+            headers,
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+          });
+        } catch (err) {
+          if (err.name === "TimeoutError" || err.name === "AbortError" || err.code === "ABORT_ERR") {
+            throw new ProviderUnavailableError(`Provider HTTP Timeout (${timeoutMs}ms): ${err.message}`, {
+              status: 504,
+            });
+          }
+          throw err;
+        }
 
         if (!res.ok) {
           const text = await res.text();
           const cleanText = text.slice(0, 500);
           const sanitizedText = rawToken ? cleanText.split(rawToken).join("[REDACTED]") : cleanText;
+          const retryAfterHeader = res.headers ? res.headers.get("retry-after") : null;
+          const retryAfterMs = parseRetryAfter(retryAfterHeader);
+
+          if (res.status === 429) {
+            throw new ProviderRateLimitError(`Provider HTTP Error (429): ${sanitizedText}`, {
+              retryAfterMs: retryAfterMs ?? 60000,
+              status: 429,
+            });
+          }
+
+          if (res.status >= 500 && res.status < 600) {
+            throw new ProviderUnavailableError(`Provider HTTP Error (${res.status}): ${sanitizedText}`, {
+              status: res.status,
+              retryAfterMs: retryAfterMs ?? undefined,
+            });
+          }
+
           throw new Error(`Provider HTTP Error (${res.status}): ${sanitizedText}`);
         }
 
-        const json = await res.json();
+        let json;
+        try {
+          json = await res.json();
+        } catch (err) {
+          throw new ProviderSchemaError(`Provider Payload Error: Invalid JSON response: ${err.message}`, {
+            status: res.status,
+          });
+        }
+
+        if (!json || typeof json !== "object") {
+          throw new ProviderSchemaError("Provider Payload Error: Expected JSON object response", {
+            status: res.status,
+          });
+        }
+
         return {
           id: json.id || json.name || "http-session",
           status: json.state || "active",

package/src/state.mjs

@@ -189,19 +189,31 @@ export function checkDailyBudget(arg1 = resolveRoot(), arg2 = 300) {
     const content = readFileSync(filePath, "utf-8");
     const lines = content.split("\n").filter(Boolean);
     let count = 0;
+    const activeIds = new Set();
     for (const line of lines) {
       try {
         const entry = JSON.parse(line);
         if (entry && entry.event === "budget_reserved") {
-          count++;
+          if (entry.reservationId) {
+            activeIds.add(entry.reservationId);
+          } else {
+            count++;
+          }
+        } else if (entry && (entry.event === "budget_rolled_back" || entry.event === "budget_released")) {
+          if (entry.reservationId) {
+            activeIds.delete(entry.reservationId);
+          } else {
+            count = Math.max(0, count - 1);
+          }
         }
       } catch (_) {}
     }
+    const used = count + activeIds.size;
     return {
-      ok: count < limit,
-      used: count,
+      ok: used < limit,
+      used,
       budget: limit,
-      remaining: Math.max(0, limit - count),
+      remaining: Math.max(0, limit - used),
     };
   } catch (_) {
     return { ok: true, used: 0, budget: limit, remaining: limit };
@@ -226,6 +238,7 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
     const filePath = join(stateDir, `ledger-${dateStr}.jsonl`);
 
     let count = 0;
+    const activeIds = new Set();
     let prevHash = "0".repeat(64);
 
     if (existsSync(filePath)) {
@@ -236,7 +249,17 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
           try {
             const entry = JSON.parse(line);
             if (entry && entry.event === "budget_reserved") {
-              count++;
+              if (entry.reservationId) {
+                activeIds.add(entry.reservationId);
+              } else {
+                count++;
+              }
+            } else if (entry && (entry.event === "budget_rolled_back" || entry.event === "budget_released")) {
+              if (entry.reservationId) {
+                activeIds.delete(entry.reservationId);
+              } else {
+                count = Math.max(0, count - 1);
+              }
             }
             if (entry && entry.hash) {
               prevHash = entry.hash;
@@ -246,8 +269,9 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
       } catch (_) {}
     }
 
-    if (count >= limit) {
-      throw new BudgetError(`Daily budget exhausted (${count}/${limit} tasks executed)`);
+    const used = count + activeIds.size;
+    if (used >= limit) {
+      throw new BudgetError(`Daily budget exhausted (${used}/${limit} tasks executed)`);
     }
 
     const timestamp = new Date().toISOString();
@@ -267,8 +291,8 @@ export function reserveBudgetAtomic(stateDirOrRoot = resolveRoot(), limit = 300,
     return {
       ok: true,
       reservationId,
-      remaining: Math.max(0, limit - (count + 1)),
-      used: count + 1,
+      remaining: Math.max(0, limit - (used + 1)),
+      used: used + 1,
     };
   }, opts);
 }
@@ -282,6 +306,11 @@ export function commitBudgetReservation(rootOrOpts = resolveRoot(), reservationI
   return appendLedger({ event: "budget_committed", reservationId }, root);
 }
 
+export function rollbackBudgetReservation(rootOrOpts = resolveRoot(), reservationId = "") {
+  const root = typeof rootOrOpts === "string" ? rootOrOpts : resolveRoot();
+  return appendLedger({ event: "budget_rolled_back", reservationId }, root);
+}
+
 export async function withBudget(fn, root = resolveRoot(), limit = 300) {
   const reservation = reserveBudget(root, limit);
   try {
@@ -289,6 +318,9 @@ export async function withBudget(fn, root = resolveRoot(), limit = 300) {
     commitBudgetReservation(root, reservation.reservationId);
     return result;
   } catch (err) {
+    if (err && typeof err === "object") {
+      err.reservationId = reservation.reservationId;
+    }
     appendLedger({ event: "budget_reservation_failed", reservationId: reservation.reservationId, error: err.message }, root);
     throw err;
   }

package/.agent/jules-queue/README.md

@@ -1,30 +0,0 @@
-# Jules Task Queue Directory
-
-Drop markdown task specification files here (e.g. `TASK-001-feature-name.md`) to queue tasks for background execution by Google Jules.
-
-### File Format Example
-
-```markdown
-# TASK-001: Implement User Rate Limiting
-
-## Objective
-Implement sliding window rate limiting for public API routes.
-
-## Execution Rules
-- Use Redis / memory store for tracking hit counts.
-- Must return HTTP 429 Too Many Requests when limit is exceeded.
-- Must pass `npm test` before submitting PR.
-```
-
-Process all queued tasks in batch:
-
-```bash
-agentctl queue
-# or npm run jules:queue
-```
-
-Or dispatch a single task using `agentctl dispatch`:
-
-```bash
-agentctl dispatch --title "TASK-001 Rate Limiting" --prompt "$(cat .agent/jules-queue/TASK-001-rate-limiting.md)"
-```

package/.agent/jules.yml

@@ -1,13 +0,0 @@
-# Google Jules Repository Configuration (Version 2)
-version: 2
-test_cmd: "npm test"
-build_cmd: ""
-forbidden_paths:
-  - ".github/**"
-  - "**/secrets/**"
-  - "**/*.pem"
-  - "**/lock-manager/**"
-  - "scripts/jules-self-audit.mjs"
-  - ".agent/jules.yml"
-allow_paths: []
-

package/.env.example

@@ -1,73 +0,0 @@
-# Google Jules Orchestration Kit - Environment Configuration Example
-# Copy this file to .env and populate with your credentials/settings.
-
-# --- Authentication & Core Settings ---
-# Google Jules API Key (Required for direct REST API dispatches)
-JULES_API_KEY=your_google_jules_api_key_here
-
-# Alias for API key (fallback if JULES_API_KEY is not set)
-# GEMINI_API_KEY=your_gemini_api_key_here
-
-# Override the Jules REST API URL
-# JULES_API_URL=https://jules.googleapis.com/v1alpha/sessions
-
-# Target GitHub Repository (Format: owner/repo)
-JULES_REPO=owner/repo
-
-# Set to "true" or "1" to run in repoless/serverless mode
-# JULES_REPOLESS=false
-
-# Enable Dry-Run mode to simulate payload dispatch without making API calls
-# JULES_DRY_RUN=false
-
-# --- Budget & Security Gatekeeper ---
-# Daily max session limit for autonomous dispatches (Default: 300)
-# JULES_DAILY_BUDGET=300
-
-# Allow modifications to command-defining files (package.json, Cargo.toml, etc.) in PRs (Default: false)
-# JULES_ALLOW_COMMAND_FILE_CHANGES=false
-
-# Allow modifications to agent rule files (AGENTS.md, JULES_RULES_TEMPLATE.md, .agent/rules/**) in PRs (Default: false)
-# JULES_ALLOW_AGENT_RULE_CHANGES=false
-
-# --- Execution Scope & Git ---
-# Base Branch for PR Audits & Merge-Base Calculations (Default: main)
-BASE_BRANCH=main
-
-# PR Head Branch (Used by CI to dynamically target branches during OODA repair)
-# GITHUB_HEAD_REF=my-feature-branch
-
-# Root directory of the project (Auto-assigned during swarm executions)
-# JULES_PROJECT_ROOT=/path/to/project
-
-# --- Swarm & Concurrency ---
-# Maximum parallel dispatches for swarm runs (Default: 3)
-JULES_SWARM_CONCURRENCY=3
-
-# Dispatch Stagger Interval in Milliseconds (Default: 1500)
-JULES_SWARM_STAGGER_MS=1500
-
-# Rate-limit for the jules:queue command (Default: 500)
-# JULES_PACE_MS=500
-
-# Use Git Worktrees instead of cloning for swarm isolation
-# JULES_USE_WORKTREES=false
-
-# Current slot index for partitioning tasks (Swarm mode)
-# JULES_SLOT_INDEX=1
-
-# Total number of slots for partitioning tasks (Swarm mode)
-# JULES_SLOT_TOTAL=3
-
-# --- CI & Output ---
-# Is this running in a CI environment? (Changes log output and fail-fast behaviors)
-# CI=true
-
-# Allow OODA Auto-Repair even in CI environments
-# ALLOW_AUTO_REPAIR=true
-
-# GitHub Actions Step Summary File Path
-# GITHUB_STEP_SUMMARY=/path/to/step_summary.md
-
-# Disable color in terminal output
-# NO_COLOR=true

package/.github/workflows/jules-audit.yml

@@ -1,49 +0,0 @@
-name: Jules PR Audit & Test Gatekeeper
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  audit-and-test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: ['20.x', '22.x', '24.x']
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      - name: Cache OODA state & ledgers
-        uses: actions/cache@v4
-        with:
-          path: .agent/state/
-          key: ooda-state-${{ runner.os }}-${{ github.run_id }}
-          restore-keys: |
-            ooda-state-${{ runner.os }}-
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Run Linter
-        run: npm run lint --if-present
-
-      - name: Run Unit Tests
-        run: npm test --if-present
-
-      - name: Run Jules PR Self-Audit Gatekeeper
-        if: matrix.node-version == '22.x' && github.event_name == 'pull_request'
-        run: node scripts/jules-self-audit.mjs
-        env:
-          CI: "true"
-          BASE_BRANCH: "main"
-