jules-orchestrator-kit 0.9.4 → 0.20.0

package/README.md

@@ -1,319 +1,114 @@
 # jules-orchestrator-kit
 
-*Disclaimer: This is an independent open-source orchestration tool and is not officially affiliated with or endorsed by Google.*
+*Disclaimer: This is an independent open-source orchestration tool for Google Jules and is not officially affiliated with or endorsed by Google.*
 
 [![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)
 
-**Turn Google Jules into an autonomous code builder that writes, tests, and fixes itself.**
-The orchestrator automates verification, scopes file boundaries, and prevents Jules from breaking your CI.
+> **v0.20.0 Early Community Release Candidate**  
+> High-volume autonomous orchestration engine for Google Jules. Built specifically to handle 300+ daily sessions and parallel agent swarms with zero external runtime dependencies.
 
-> [!WARNING]
-> **Alpha Release:** This kit is in active development. Please exercise caution before integrating it into critical production pipelines.
+---
 
-> [!CAUTION]
-> **Task Limit Warning:** Autonomous loops can quickly consume your daily API limits. We strongly recommend starting with `JULES_DRY_RUN=1` to understand the workflow before scaling up.
+## ⚡ 2-Minute Quickstart
 
-## Prerequisites
-To use this kit, you will need:
-- Node.js `18.0.0` or higher
-- `git` installed and available in your PATH
-- A Google Jules REST API key (set as `JULES_API_KEY`) **OR** the native `jules` binary in your PATH.
+Get up and running in under 2 minutes:
 
-## Quick Start
-Initialize your repository:
 ```bash
+# 1. Install or initialize in your target codebase
 npx jules-orchestrator-kit init
-```
-
-Dispatch a task or run the queue using `agentctl`:
-```bash
-agentctl dispatch --title "Refactor Auth" --prompt "Implement JWT verification in auth handler"
-agentctl queue
-agentctl gate
-```
 
-> 💡 **Unified Engine CLI (`agentctl`)**:
-> `agentctl` is the zero-dependency CLI executable that powers dispatching, safety gate auditing, mutex locks, and swarm management across all project types (Node, Rust, Go, Python, etc.).
-> Legacy `scripts/jules-*.mjs` shims are preserved for backward compatibility.
+# 2. Dispatch a task (Dry-Run mode for testing)
+JULES_DRY_RUN=1 npx agentctl dispatch \
+  --title "Add JWT Validator" \
+  --prompt "Implement JWT validation middleware with unit tests"
 
----
+# 3. Run security & verification gatekeeper
+npx agentctl gate
 
-## How It Works
-
-1. **You Assign Task:** Define what needs fixing or building (supports text and multimodal image mockups).
-2. **Jules Writes Code:** Proposes changes in an isolated Git worktree sandbox.
-3. **Run Tests & Linters:** The Gatekeeper runs your test suite, linters, and type checks.
-4. **Self-Correction:** If anything fails, Jules automatically retries with fixes (OODA loop).
-5. **Safe Delivery:** Once tests pass, the PR is verified and ready for review.
-
-```mermaid
-sequenceDiagram
-    autonumber
-    
-    box "Client Edge" #F4F4F4
-        actor Trigger as Client (CLI / CI / SDK)
-    end
-    
-    box "Control Plane" #E8F4F8
-        participant Orc as Orchestrator Core
-        participant Envelope as Task Envelope Validator
-        participant Gate as Self-Audit Gatekeeper
-    end
-    
-    box "Execution Sandbox" #F8E8E8
-        participant API as Google Jules API
-        participant Git as Git Worktree Sandbox
-    end
-
-    Trigger->>+Orc: Dispatch Task Payload / Envelope
-    
-    note over Orc,Envelope: Phase 1: Pre-Flight Premise & Security Validation
-    Orc->>+Envelope: Validate Envelope (referenced_paths exist? base commit fresh?)
-    alt Premise Failure / Missing Referenced Paths / Stale Base
-        Envelope-->>Orc: Validation Failed (Premise Error)
-        Orc-->>Trigger: Abort Pre-Dispatch (Exit 1)
-    else Envelope Validated
-        Envelope-->>-Orc: Envelope Approved
-        Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
-        Orc->>+Git: Provision Isolation Sandbox (git worktree)
-        Git-->>-Orc: Sandbox Ready
-    end
-    
-    loop OODA Repair Cycle (Max 3 Retries)
-        note over Orc,Git: Phase 2: Agent Execution & Dispatch
-        Orc->>+API: Dispatch Task + <MCP_DIRECTIVE> & Target Scope
-        API->>+Git: Apply Proposed Code Changes
-        Git-->>-API: Changes Written
-        API-->>-Orc: Execution Complete
-        
-        note over Orc,Gate: Phase 3: Multi-Gate Verification & Risk Classification
-        Orc->>+Gate: Trigger Self-Audit (trusted origin/main rules)
-        
-        Gate->>+Git: Run Scope, Payload & Stale-Base Audit (`git diff`)
-        Git-->>-Gate: Diff Stats & Base Commit Age
-        
-        alt Scope Breach / Payload > 75 KB / Stale Base > 25 commits
-            Gate-->>Orc: Security / Scope / Stale-Base Violation
-            Orc->>Orc: Record Telemetry (metrics.jsonl)
-            Orc-->>Trigger: Abort Execution (Exit 3)
-            break Fatal Security or Base Error
-                Orc->>Git: Teardown Worktree Sandbox
-            end
-        else Static Scope & Base Passed
-            Gate->>Gate: Classify Risk Tier (R0 Cosmetic, R1 Routine, R2 Consequential, R3 Restricted)
-            Gate->>+Git: Run Integrity Checks (Asset Magic-Bytes, Rules Budget, testCmd & buildCmd)
-            Git-->>-Gate: Execution & Integrity Proof (stdout/stderr)
-        end
-
-        alt 100% Verification Suite & Integrity Passed
-            Gate-->>-Orc: Verification Success + Risk Tier Metadata
-            Orc->>+Git: Commit & Push to Remote Branch / PR
-            Git-->>-Orc: PR Ready (Attached Execution Receipts)
-            Orc->>Orc: Record Telemetry (metrics.jsonl)
-            Orc-->>Trigger: Dispatch Succeeded (Exit 0)
-            break Task Completed
-                Orc->>Git: Teardown Worktree Sandbox
-            end
-        else Verification Failed
-            Gate-->>Orc: Verification Failed (Stderr Trace output)
-            Orc->>Orc: Record Failure Telemetry
-            
-            alt Retries Remaining (< 3)
-                Orc->>Orc: Construct Repair Prompt with Stderr Trace
-            else Max Retries Exceeded (3/3)
-                Orc-->>-Trigger: Abort & Log Diagnostic Feedback (Exit 4)
-                Orc->>Git: Teardown Worktree Sandbox
-            end
-        end
-    end
+# 4. Start stdio MCP Server (for Cursor, Claude Code, or AGY integration)
+npx agentctl mcp
 ```
 
-> 💡 **Core Architectural Invariants**:
-> - **Task Envelope Premise Validation**: Pre-flight checks verify referenced paths and base freshness before dispatching tasks to prevent session burnout.
-> - **Risk Tier Classification Engine (R0–R3)**: Classifies changes by blast radius to route auto-merge vs mandatory human review.
-> - **Zero-Trust Base-Branch Security**: Security rules (`forbidden_paths`) are fetched exclusively from `origin/main` (never untrusted PR branches).
-> - **Asset & Rules Integrity**: Guards binary assets against HTML corruption and enforces character/line budgets on rule files.
-> - **Automatic PII & Secret Redaction**: Outbound task prompts are automatically sanitized to redact API secrets and mask sensitive PII (emails, IPs, phone numbers).
-> - **Ledger Hash-Chain Integrity**: Hashing over JSONL event streams detects unauthorized log tampering or record deletions.
->
-> 🔍 For a deep dive into the execution protocol, see the [Architecture & Pipeline Flow](docs/architecture.md).
-
 ---
 
-## Configuration
-
-The orchestrator automatically detects your tech stack, but you can edit `.agent/jules.yml` for fine-grained control:
-
-```yaml
-# Google Jules Repository Configuration (Version 2)
-version: 2
-test_cmd: "npm test"
-build_cmd: "npm run build"
-forbidden_paths:
-  - ".github/**"
-  - "**/secrets/**"
-  - "**/*.pem"
-  - "**/lock-manager/**"
-  - "scripts/jules-*"
-  - ".agent/jules.yml"
-allow_paths: []
-```
+## 🚀 Built for High-Volume Jules Swarms
 
----
+`jules-orchestrator-kit` provides the production-hardened control plane needed to execute parallel Google Jules agent swarms safely:
 
-## Expand with MCP
+- **Parallel Agent Swarms**: Execute multi-agent task batches concurrently with deterministic lock management and automatic collision prevention.
+- **Self-Healing OODA Loop**: Automatic test/build verification and repair loop with sliding-window thrash detection to halt non-convergent agent loops ($A \rightarrow B \rightarrow A \rightarrow B$) and preserve API token budgets.
+- **4-Phase Security Gatekeeper**: Fails closed on untrusted PRs by verifying Scope (`forbidden_paths`), Diff Payload Size, Secret Entropy (> 3.6 bits), and Trusted Build/Test Execution.
 
-All task dispatches dynamically inject `<MCP_DIRECTIVE>` envelopes into task prompts. This forces Jules to adhere to strict read-before-write invariants.
+---
 
-You can supercharge Jules with external MCP servers by connecting them to your environment, granting Jules direct access to your infrastructure and real-time documentation. Examples:
-* **SaaS APIs & Tooling:** Context 7, Linear, and v0.
-* **Databases & Cloud:** Render, Neon, Supabase, Stitch.
-* **Framework Documentation:** Astro Docs, Cloudflare Docs, Next.js Docs.
+## ⚙️ Core Technical Architecture
 
----
+Built strictly on native Node.js 18+ ESM with **Zero External Runtime Dependencies** (`"node": ">=18.0.0"`):
 
-## Integration Interfaces
+- **Linearizable VFS Mutex (`src/state.mjs`)**: Kernel-level directory mutex (`withVfsMutex`) guaranteeing serial linearizability for SHA-256 hash-chained session ledgers under high concurrency.
+- **PID Recycling & Stale Lock Protection (`src/state.mjs`)**: Linux `/proc/<pid>/stat` launch-time validation prevents false-positive lock reaps from recycled OS process IDs.
+- **Memory-Bounded Content-Length MCP Streaming (`src/mcp.mjs`)**: Native MCP server over stdio streams using `McpFrameDecoder` with a 4 MB memory safety ceiling and panic boundaries to prevent stdout stack trace leaks.
+- **Process Group Isolation (`src/process-group.mjs`)**: `ProcessGroupManager` creates isolated process groups (`detached: true`) and catches `SIGINT`/`SIGTERM`/`exit` signals to execute `process.kill(-pgid)`, guaranteeing zero zombie processes.
+- **TOCTOU & Symlink Defense (`src/security.mjs`)**: `safeAtomicWrite()` uses `O_CREAT | O_EXCL | O_WRONLY` temp files with `fsyncSync` + `renameSync` and `lstatSync`/`realpathSync` symlink checks.
+- **3-Way Structural AST/JSON Merge (`scripts/jules-merge-swarm.mjs`)**: Pure Node `deepMerge3Way()` algorithm for recursive object and array merges executed in isolated temporary directories (`os.tmpdir()`).
 
-The orchestrator supports three primary integration channels:
+---
 
-**1. Direct REST API Mode (`jules.googleapis.com`)**
-When `JULES_API_KEY` and `JULES_REPO` are present in your environment, payloads are dispatched directly to the official Google Jules REST API endpoint. Handles HTTP 429 rate limits gracefully.
+## 🛠️ CLI Command Reference (`agentctl`)
 
-**2. Native Jules CLI Fallback**
-If no API key is configured, the kit seamlessly falls back to invoking your local `jules` CLI binary via standard streams.
+| Command | Usage | Description |
+| :--- | :--- | :--- |
+| `agentctl dispatch` | `agentctl dispatch --title "..." --prompt "..."` | Dispatches an autonomous task to Jules |
+| `agentctl gate` | `agentctl gate [--fix] [--base main]` | Runs 4-Phase Safety Gatekeeper against workspace |
+| `agentctl queue` | `agentctl queue` | Processes pending task queue from `.agent/jules-queue/` |
+| `agentctl swarm` | `agentctl swarm` | Executes parallel swarm task queue |
+| `agentctl merge-swarm` | `agentctl merge-swarm` | Performs 3-way structural merge on completed swarm PRs |
+| `agentctl mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server |
+| `agentctl doctor` | `agentctl doctor` | Verifies stack configuration, environment, and budget |
 
-**3. Programmatic Node.js SDK (`index.mjs`)**
-Downstream Node.js tools, MCP servers, and LLM orchestrators can import kit functions directly:
-```js
-import { gate, dispatch, validateEnvelope, classifyRiskTier, checkAssetIntegrity, checkRulesBudget, redactSecrets } from "jules-orchestrator-kit";
+---
 
-// Anonymize sensitive PII (emails, IPs, phone numbers) before sending prompts
-const cleanPrompt = anonymizePii("Contact support at john@example.com");
+## 📋 Exit Code Protocol
 
-// Programmatically dispatch tasks
-await dispatch({ title: "Refactor Auth", prompt: cleanPrompt });
+Standardized exit codes enforced across all CLI utilities:
 
-// Run 4-phase safety gate audit
-const audit = await gate({ base: "main" });
-```
+| Code | Status | Description |
+| :---: | :--- | :--- |
+| `0` | **Success** | Task completed cleanly; verification passed 100%. |
+| `1` | **Arg / Pre-Dispatch Failure** | Invalid arguments, prompt > 50 KB, or pre-dispatch error. |
+| `2` | **API / Network Failure** | Jules API rate-limit (429), `FAILED_PRECONDITION`, or timeout. |
+| `3` | **Scope Violation** | Attempted modification of protected/forbidden files. |
+| `4` | **OODA Exhausted / Regression** | Verification failed after max repair attempts or thrash loop. |
+| `5` | **Diff Payload Exceeded** | Git diff exceeds payload budget (`limits.diffKb`, default 75 KB). |
+| `6` | **Secret Detected** | High-confidence secret or token detected in patch diff. |
+| `7` | **Budget Exhausted** | Daily task session quota limit reached (`limits.dailyTasks`, default 300). |
 
 ---
 
-## Known Limitations
-
-**Code Suggestions (Web UI Only)**
-Currently, there is no way to automatically extract "Suggestions" (the inline code review comments Jules sometimes proposes instead of direct commits) via the CLI or API. Suggestions can only be read directly inside the **Jules Web UI**.
+## 🤝 Join the Community & Field-Testing
 
-*Workaround for Local LLM Users:* If you are tinkering with Jules alongside a local LLM and Jules leaves a Suggestion, the easiest workflow is to open the Jules Web UI, copy the suggestion block, and paste it back into your local LLM.
+We are actively field-testing `v0.20.0` across 300+ daily autonomous sessions and opening the kit to the Google Jules developer community for feedback and contributions!
 
----
+- **Test & Benchmark**: Clone the repository, test your edge cases, and run parallel swarms against your codebases.
+- **Report Issues**: Found a bug, state race condition, or edge-case failure? Open an issue on GitHub.
+- **Submit PRs**: We welcome contributions! Ensure all additions preserve our Zero Runtime Dependency invariant and pass `npm test` & `npm run lint`.
 
-## Supported Tech Stacks
-
-| Stack / Ecosystem           | Manifest / Workspace File             | Test Command                             | Build Command                            |
-| --------------------------- | ------------------------------------- | ---------------------------------------- | ---------------------------------------- |
-| **Turborepo**               | `turbo.json`                          | `npx turbo run test --filter=...`        | `npx turbo run build --filter=...`       |
-| **pnpm Workspace**          | `pnpm-workspace.yaml`                 | `pnpm --filter=... test`                 | `pnpm --filter=... build`                |
-| **Nx Workspace**            | `nx.json`                             | `npx nx run-many -t test -p ...`         | `npx nx run-many -t build -p ...`        |
-| **Bun**                     | `bunfig.toml` / `bun.lockb`           | `bun test`                               | `bun run build`                          |
-| **Deno**                    | `deno.json` / `deno.jsonc`            | `deno test`                              | `deno task build`                        |
-| **JavaScript / TypeScript** | `package.json`                        | `npm test`                               | `npm run build`                          |
-| **Rust**                    | `Cargo.toml`                          | `cargo test --workspace`                 | `cargo build`                            |
-| **Go**                      | `go.mod`                              | `go test ./...`                          | `go build ./...`                         |
-| **Python**                  | `pyproject.toml` / `requirements.txt` | `pytest`                                 | *(none)*                                 |
-| **Elixir**                  | `mix.exs`                             | `mix test`                               | `mix compile`                            |
-| **Ruby**                    | `Gemfile`                             | `bundle exec rake test`                  | *(none)*                                 |
-| **Swift**                   | `Package.swift`                       | `swift test`                             | `swift build`                            |
-| **Java (Maven/Gradle)**     | `pom.xml` / `build.gradle`            | `mvn test` / `./gradlew test`            | `mvn compile` / `./gradlew assemble`     |
-| **C / C++**                 | `Makefile`                            | `make test`                              | `make build`                             |
+### Running Tests Locally
 
----
+```bash
+# Clone the repository
+git clone https://github.com/FullThrottle83/jules-orchestrator-kit.git
+cd jules-orchestrator-kit
 
-## Reference Material
-
-### CLI Commands
-All commands are registered in `package.json` and can be run via `npm run <command>`.
-
-| Command | Description |
-| ------- | ----------- |
-| `npm run init` | Initializes the orchestrator and `.agent/` directory |
-| `npm run test` | Runs the orchestrator kit's own unit tests |
-| `npm run jules:dispatch` | Dispatches a single task directly to Jules |
-| `npm run jules:queue` | Runs the local queue processor (picks up tasks from `.agent/jules-queue`) |
-| `npm run jules:create` | Scaffolds a new boilerplate task markdown file |
-| `npm run jules:status` | Shows real-time 3-bucket status (Action Required, In Progress, Completed) |
-| `npm run jules:audit` | Runs the self-audit gatekeeper (verifies tests, forbidden paths, and scope) |
-| `npm run jules:cleanup` | Audits and closes merged or stale REST sessions |
-| `npm run jules:scan` | Scans the codebase for TODO/FIXME comments and generates a suggested tasks file |
-| `npm run jules:swarm` | Launches a multi-agent swarm in parallel across isolated worktrees |
-| `npm run jules:merge-swarm` | Autonomous PR merge engine with Safety Gate lock verification |
-| `npm run jules:nightly` | Nightly maintenance job (usually triggered in CI) |
-
-### Specialist Agent Prompts & Templates (`.agent/prompts/`)
-The kit includes pre-configured single-responsibility prompt presets in `.agent/prompts/`:
-- **`Overseer.md`**: Codebase architecture auditor & technical debt mapper.
-- **`Bolt.md`**: Performance micro-optimizer and payload governor (enforces < 75 KB payload diff limits).
-- **`Sentinel.md`**: Security audit specialist for input sanitization and secret scanning.
-- **`Task_Template.md`**: Machine-readable master task prompt template schema.
-
-### Environment Variables
-
-| Variable | Description |
-| -------- | ----------- |
-| `JULES_API_KEY` | Your Google Jules REST API key (required for API mode) |
-| `GEMINI_API_KEY` | Alias for `JULES_API_KEY` (fallback) |
-| `JULES_API_URL` | Override the Jules REST API URL |
-| `JULES_REPO` | Target GitHub Repository (Format: `owner/repo`) |
-| `JULES_REPOLESS` | Set to `true` or `1` to run in repoless/serverless mode |
-| `JULES_DRY_RUN` | Set to `true` or `1` to simulate dispatching without making API calls |
-| `JULES_DAILY_BUDGET` | Daily max session budget for autonomous dispatches (Default: `300`) |
-| `JULES_MAX_DIFF_KB` | Maximum git diff payload size in KB before aborting with Exit Code 5 (Default: `50`) |
-| `JULES_ALLOW_COMMAND_FILE_CHANGES` | Set to `true` to allow PR changes to command/config files like `package.json`, `tsconfig.json`, `vite.config.ts` (Default: `false`) |
-| `JULES_ALLOW_AGENT_RULE_CHANGES` | Set to `true` to allow PR changes to agent rule files like `AGENTS.md`, `JULES_RULES_TEMPLATE.md` (Default: `false`) |
-| `BASE_BRANCH` | Base branch for PR Audits & Merge-Base calculations (Default: `main`) |
-| `GITHUB_HEAD_REF` | PR Head Branch (Used dynamically by CI during OODA repair) |
-| `JULES_PROJECT_ROOT` | Root directory of the project (Auto-assigned during swarm executions) |
-| `JULES_SWARM_CONCURRENCY` | Maximum parallel dispatches for swarm runs (Default: `3`) |
-| `JULES_SWARM_STAGGER_MS` | Dispatch stagger interval in milliseconds (Default: `1500`) |
-| `JULES_PACE_MS` | Rate-limit for the `jules:queue` command (Default: `500`) |
-| `JULES_USE_WORKTREES` | Use Git Worktrees instead of cloning for swarm isolation (Default: `false`) |
-| `JULES_SLOT_INDEX` | Current slot index for partitioning tasks (Swarm mode) |
-| `JULES_SLOT_TOTAL` | Total number of slots for partitioning tasks (Swarm mode) |
-| `CI` | Set to `true` to change log output and fail-fast behaviors for CI environments |
-| `ALLOW_AUTO_REPAIR` | Set to `true` to allow OODA Auto-Repair even when running in CI |
-| `GITHUB_STEP_SUMMARY` | GitHub Actions Step Summary File Path |
-| `NO_COLOR` | Set to `true` to disable ANSI color output |
-
-> [!NOTE]
-> **Scope Enforcement via `allow_paths`**
-> In `.agent/jules.yml`, defining `allow_paths` acts as a strict allowlist (deny-by-default). When non-empty, any file modified outside `allow_paths` will trigger a security violation (Exit Code 3). `forbidden_paths` always take absolute precedence and cannot be overridden.
-
-### Exit Codes
-The Gatekeeper (`jules-self-audit.mjs` and related scripts) uses standard exit codes to signal status to CI systems.
-
-| Code | Meaning | Action Taken |
-| ---- | ------- | ------------ |
-| `0`  | **Success** | All tests and security checks passed. |
-| `1`  | **Pre-Dispatch / Arg Error** | Missing dependencies, prompt > 50 KB, syntax error, or pre-dispatch failure. |
-| `2`  | **API / Network / Quota Error** | REST API HTTP 429 rate limit, HTTP 400 `FAILED_PRECONDITION` quota (~30 active limit), or connection timeout. |
-| `3`  | **Security / Scope Violation** | Modified file breached `forbidden_paths` or changed command-defining files (`package.json`, `Cargo.toml`). Fails closed immediately. |
-| `4`  | **Verification Exhausted** | Tests failed and the OODA Auto-Repair loop either exhausted its max retries (3) or is disabled. |
-| `5`  | **Diff Payload Limit** | Diff payload size exceeded payload governor budget (`JULES_MAX_DIFF_KB`, default 50 KB). Split task. |
-| `6`  | **Secret Leak Prevented** | High-confidence secret or private key pattern detected in diff. Aborted immediately. |
-| `7`  | **Budget Exhausted** | Daily session budget limit reached or budget state locked. |
+# Run ESLint & node unit test suite (100% zero external runtime deps)
+npm run lint
+npm test
+```
 
 ---
 
-## Contributing
-We welcome contributions! Please follow these core principles:
-1. **Zero Runtime Dependencies**: Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`).
-2. **Verification Suite**: Ensure 100% of unit tests pass cleanly (`npm test`).
-3. **Conventional Commits**: Use standardized prefixes (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
-4. **Cross-Platform Compatibility**: Normalize Windows backslashes (`\`) to POSIX slashes (`/`) for glob patterns and paths.
-
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+## 📄 License
 
-## License
-MIT License - feel free to use, modify, and share!
+Distributed under the [MIT License](LICENSE).

package/bin/agentctl.mjs

@@ -13,7 +13,7 @@ const command = args[0];
 
 function printHelp() {
   console.log(`
-🚀 agentctl v0.9.4 — Universal Agent Orchestrator & Safety Gatekeeper
+🚀 agentctl v0.20.0 — Universal Agent Orchestrator & Safety Gatekeeper
 
 Usage: agentctl <command> [options]
 

package/index.mjs

@@ -5,7 +5,7 @@
  * security auditing, repo gating, and state operations.
  */
 
-export { loadConfig, detectStack, resolveVerify, resolveRoot, normalizePath } from "./src/config.mjs";
+export { loadConfig, detectStack, resolveVerify, resolveRoot, normalizePath, TIER_PRESETS } from "./src/config.mjs";
 export {
   shannonEntropy,
   redactSecrets,
@@ -19,14 +19,23 @@ export { createProvider, JULES_PRESET, CLAUDE_PRESET, CODEX_PRESET } from "./src
 export {
   appendLedger,
   readLedger,
+  verifyLedgerIntegrity,
+  reserveBudget,
+  commitBudgetReservation,
   withBudget,
   checkDailyBudget,
   acquireLock,
   releaseLock,
   lockStatus,
 } from "./src/state.mjs";
-export { gate, dispatch, repair, run } from "./src/engine.mjs";
+export { gate, dispatch, repair, run, fingerprintFailureState } from "./src/engine.mjs";
 export { validateEnvelope } from "./src/envelope.mjs";
+export {
+  createExecutionEnvelope,
+  verifyExecutionEnvelope,
+  freezeExecutionEnvelope,
+  hashExecutionEnvelope,
+} from "./src/execution_envelope.mjs";
 export { checkAssetIntegrity } from "./src/asset_integrity.mjs";
 export { classifyRiskTier, RISK_TIERS } from "./src/risk.mjs";
 export { checkRulesBudget } from "./src/rules_budget.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.9.4",
+  "version": "0.20.0",
   "description": "Orchestration kit for running Google Jules autonomous agents.",
   "repository": {
     "type": "git",

package/scripts/jules-merge-swarm.mjs

@@ -1,30 +1,198 @@
 #!/usr/bin/env node
 
 /**
- * Backward compatibility shim for jules-merge-swarm.mjs in v0.9.0.
+ * Swarm branch merger with 3-way structural JSON/object merge, git merge-file execution
+ * isolated in os.tmpdir(), and safety gate checking.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { writeFileSync, readFileSync, existsSync, readdirSync, rmSync, mkdtempSync } from "node:fs";
 import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { classifyRiskTier, RISK_TIERS } from "../src/risk.mjs";
+import { changedFiles } from "../src/git.mjs";
 
+export const EXIT = Object.freeze({
+  SUCCESS: 0,
+  R3_RESTRICTED: 3,
+  MERGE_CONFLICT: 4,
+});
+
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function isPlainObject(v) {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    !Array.isArray(v) &&
+    (Object.getPrototypeOf(v) === null || Object.getPrototypeOf(v) === Object.prototype)
+  );
+}
+
+function deepClone(v) {
+  if (v === undefined) return undefined;
+  return JSON.parse(JSON.stringify(v));
+}
+
+function stableStringify(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(v).filter((k) => !BLOCKED_KEYS.has(k)).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(",")}}`;
+}
+
+function deepEqual(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
+
+/**
+ * Recursive 3-way structural object & array merge.
+ */
+export function deepMerge3Way(base, ours, theirs, path = "$") {
+  const conflicts = [];
+  if (deepEqual(ours, theirs)) return { merged: deepClone(ours), conflicts };
+  if (deepEqual(ours, base)) return { merged: deepClone(theirs), conflicts };
+  if (deepEqual(theirs, base)) return { merged: deepClone(ours), conflicts };
+
+  if (isPlainObject(base) && isPlainObject(ours) && isPlainObject(theirs)) {
+    const merged = {};
+    const safeBase = base || {};
+    const safeOurs = ours || {};
+    const safeTheirs = theirs || {};
+    const keys = new Set([
+      ...Object.keys(safeBase),
+      ...Object.keys(safeOurs),
+      ...Object.keys(safeTheirs),
+    ]);
+    for (const k of keys) {
+      if (BLOCKED_KEYS.has(k)) continue;
+      const childPath = `${path}.${k}`;
+      const b = safeBase[k], o = safeOurs[k], t = safeTheirs[k];
+      if (o === undefined && t === undefined) continue;
+      if (o === undefined) { merged[k] = deepClone(t); continue; }
+      if (t === undefined) { merged[k] = deepClone(o); continue; }
+      const sub = deepMerge3Way(b, o, t, childPath);
+      merged[k] = sub.merged;
+      conflicts.push(...sub.conflicts);
+    }
+    return { merged, conflicts };
+  }
+
+  if (Array.isArray(ours) && Array.isArray(theirs)) {
+    const baseArr = Array.isArray(base) ? base : [];
+    const minLen = Math.min(ours.length, theirs.length);
+    const merged = [];
+    for (let i = 0; i < minLen; i++) {
+      const sub = deepMerge3Way(baseArr[i], ours[i], theirs[i], `${path}[${i}]`);
+      merged.push(sub.merged);
+      conflicts.push(...sub.conflicts);
+    }
+    if (ours.length > minLen && theirs.length <= minLen) {
+      merged.push(...ours.slice(minLen).map(deepClone));
+    } else if (theirs.length > minLen && ours.length <= minLen) {
+      merged.push(...theirs.slice(minLen).map(deepClone));
+    } else if (ours.length > minLen && theirs.length > minLen) {
+      conflicts.push({
+        path: `${path}[tail]`,
+        base: baseArr.slice(minLen),
+        ours: ours.slice(minLen),
+        theirs: theirs.slice(minLen),
+      });
+      merged.push(...ours.slice(minLen).map(deepClone));
+    }
+    return { merged, conflicts };
+  }
+
+  conflicts.push({ path, base: deepClone(base), ours: deepClone(ours), theirs: deepClone(theirs) });
+  return { merged: deepClone(ours), conflicts };
+}
+
+/**
+ * Executes a function inside a temporary directory in os.tmpdir() with guaranteed cleanup.
+ */
+export function withTempDir(prefix, fn) {
+  const dir = mkdtempSync(join(tmpdir(), prefix || "jules-merge-"));
+  try {
+    return fn(dir);
+  } finally {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch (_) {}
+  }
+}
+
+/**
+ * Attempts a 3-way text file merge using git merge-file inside os.tmpdir().
+ */
+export function attemptCodeMergeFile(repoRoot, relPath, oursContent, baseContent, theirsContent) {
+  return withTempDir("jules-merge-", (tmp) => {
+    const baseFile = join(tmp, "base");
+    const oursFile = join(tmp, "ours");
+    const theirsFile = join(tmp, "theirs");
+    writeFileSync(baseFile, baseContent ?? "", "utf-8");
+    writeFileSync(oursFile, oursContent ?? "", "utf-8");
+    writeFileSync(theirsFile, theirsContent ?? "", "utf-8");
+
+    const res = spawnSync("git", ["merge-file", "-p", "--diff3", oursFile, baseFile, theirsFile], {
+      encoding: "utf-8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+
+    if (res.error) {
+      return { ok: false, conflicts: 0, error: res.error.message };
+    }
+    const conflictCount = res.status && res.status > 0 ? res.status : 0;
+    const merged = res.stdout ?? "";
+    return {
+      ok: conflictCount === 0,
+      merged,
+      conflicts: conflictCount,
+    };
+  });
+}
+
+/**
+ * Checks safety gate against active worker locks and risk tiers.
+ */
 export function checkSafetyGate(branchName = "", projectRoot = process.cwd()) {
   const locksDir = join(projectRoot, ".agent/state/locks");
-  if (!existsSync(locksDir)) return { safe: true };
+  if (existsSync(locksDir)) {
+    try {
+      const files = readdirSync(locksDir);
+      for (const f of files) {
+        if (!f.endsWith(".json")) continue;
+        const content = readFileSync(join(locksDir, f), "utf-8");
+        const parsed = JSON.parse(content);
+        if (parsed.branch === branchName) {
+          return { safe: false, reason: `Active lock held by worker ${parsed.agent || "unknown"}` };
+        }
+      }
+    } catch (_) {}
+  }
+
+  // Check R3 risk tier if files modified
   try {
-    const files = readdirSync(locksDir);
-    for (const f of files) {
-      if (!f.endsWith(".json")) continue;
-      const content = readFileSync(join(locksDir, f), "utf-8");
-      const parsed = JSON.parse(content);
-      if (parsed.branch === branchName) {
-        return { safe: false, reason: `Active lock held by worker ${parsed.agent || "unknown"}` };
+    const files = changedFiles(projectRoot, process.env.BASE_BRANCH || "main");
+    if (files.length > 0) {
+      const tier = classifyRiskTier(files);
+      if (tier.tier === RISK_TIERS.R3) {
+        return { safe: false, reason: `R3 Restricted Path violation: ${tier.reason}` };
       }
     }
   } catch (_) {}
+
   return { safe: true };
 }
 
 if (process.argv[1] && process.argv[1].endsWith("jules-merge-swarm.mjs")) {
+  const branchName = process.argv[2] || "";
+  const gateResult = checkSafetyGate(branchName);
+  if (!gateResult.safe) {
+    console.error(`[merge-swarm] Safety gate check failed: ${gateResult.reason}`);
+    process.exit(EXIT.R3_RESTRICTED);
+  }
+
   console.log("No open Jules PRs found.");
-  process.exit(0);
+  process.exit(EXIT.SUCCESS);
 }
+