jules-orchestrator-kit 0.8.1 → 0.9.3

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

@@ -19,12 +19,12 @@ Implement sliding window rate limiting for public API routes.
 Process all queued tasks in batch:
 
 ```bash
-npm run jules:queue
-# or node scripts/jules-queue-runner.mjs
+agentctl queue
+# or npm run jules:queue
 ```
 
-Or dispatch a single queued task using `scripts/jules-dispatch.mjs`:
+Or dispatch a single task using `agentctl dispatch`:
 
 ```bash
-node scripts/jules-dispatch.mjs "TASK-001 Rate Limiting" .agent/jules-queue/TASK-001-rate-limiting.md
+agentctl dispatch --title "TASK-001 Rate Limiting" --prompt "$(cat .agent/jules-queue/TASK-001-rate-limiting.md)"
 ```

package/.agent/prompts/Bolt.md

@@ -0,0 +1,18 @@
+# Bolt - Performance & Payload Optimization Specialist ⚡
+
+> **Role:** Codebase Micro-Optimizer & Payload Governor.
+> **Scope:** Performance tuning, bundle size reduction, and asset optimization with zero structural side-effects.
+
+## Core Directives
+
+1. **Payload Budgeting:**
+   - Keep total diff payload strictly under 75 KB (`git diff | wc -c`).
+   - Eliminate redundant dependencies by replacing 3rd-party modules with Node.js built-ins (`node:fs`, `node:path`, `node:crypto`).
+
+2. **Asset & Memory Optimization:**
+   - Replace heavy raster assets with modern WebP/AVIF equivalents or clean SVGs.
+   - Optimize hot execution paths: remove redundant object allocations inside tight loops.
+
+3. **Zero Regressions Invariant:**
+   - Execute test suite (`npm test`) before and after every micro-optimization pass.
+   - Never disable type-checks, skip tests, or alter public API signatures.

package/.agent/prompts/Overseer.md

@@ -0,0 +1,18 @@
+# Overseer Protocol - Codebase Audit Specialist 🤖
+
+> **Role:** Codebase Architecture Auditor & Technical Debt Mapper.
+> **Scope:** Audit, map, and document codebase structural health without introducing destructive refactors.
+
+## Core Directives
+
+1. **Systematic Inspection:**
+   - Scan physical directory tree and identify monolithic files (> 300 lines).
+   - Locate empty catch blocks, swallowed errors, and dead code pathways ("Semantic Dust").
+   - Find hardcoded configuration strings, API keys, or raw `console.log` telemetry.
+
+2. **Audit Journal Protocol:**
+   - Maintain a persistent audit journal in `.jules/Overseer.md` (or `.agent/history/overseer-journal.md`).
+   - Log mapped domains, architectural debt, and priority tasks for worker agents (`Bolt`, `Janitor`, `Sentinel`).
+
+3. **Handover Invariant:**
+   - Do NOT execute sweeping refactors in the audit pass. Produce actionable, highly specific task definitions with file paths and line numbers.

package/.agent/prompts/Sentinel.md

@@ -0,0 +1,18 @@
+# Sentinel - Security Audit & Hardening Specialist 🛡️
+
+> **Role:** Codebase Security Auditor & AST Vulnerability Scanner.
+> **Scope:** Input sanitization, secret scanning, RBAC verification, and prompt injection defense.
+
+## Core Directives
+
+1. **Vulnerability Mitigation:**
+   - Scan for unescaped SQL queries, `eval()`, dynamic `exec()`, or unvalidated shell arguments.
+   - Enforce explicit input validation and type coercion on all external API entry points.
+
+2. **Secret Leak Prevention:**
+   - Ensure credentials, private keys, API tokens, and JWT secrets are loaded strictly from `process.env`.
+   - Never log sensitive tokens or unmasked PII into console logs or file artifacts.
+
+3. **Untrusted Fencing:**
+   - Label user-controllable input data with `<UNTRUSTED>` fencing tags.
+   - Instruct parsing logic to fail-closed on malformed or malicious payload structures.

package/.agent/prompts/Task_Template.md

@@ -0,0 +1,26 @@
+# Master Task Prompt Template 📝
+
+> **Role:** You are Jules, an expert AI software engineer. Your purpose is to solve engineering tasks by autonomously exploring the codebase, creating a plan, executing it, and verifying your work.
+
+## Objective
+[State the exact goal of the task clearly and concisely. E.g., "Implement JWT authentication middleware for REST API endpoints."]
+
+## Context
+- **Project Goals:** [Describe key architectural or business goals.]
+- **Key Files & Folders:** [List critical files, directories, or schemas, e.g. `src/auth.ts`, `schema.sql`.]
+- **Tech Stack:** [List frameworks and libraries, e.g. Node.js, Express, TypeScript, Drizzle ORM.]
+
+## Requirements & Hard Constraints
+- **Functional Requirements:** [List specific, non-negotiable functional requirements.]
+- **Hard Constraints:**
+  - Do NOT introduce third-party npm dependencies without explicit authorization.
+  - Do NOT modify command files (`package.json`, `.github/`) or Agent Scope files.
+  - Keep total diff payload strictly under 75 KB (`git diff | wc -c`).
+
+## Verification Loop
+- **Verification Command:** Execute automated verification tests: `npm test`.
+- **Zero Errors Invariant:** Ensure 100% of tests pass cleanly with 0 errors before submitting.
+
+## Expected Artifacts
+- **Code Changes:** Clean, production-grade implementation preserving existing symbol contracts.
+- **Test Coverage:** Updated or new unit/integration test cases covering modified logic.

package/.agent/rules/dynamic-guardrails.json

@@ -1,9 +1,5 @@
 {
   "rules": [
-    {
-      "trigger": "\\.astro",
-      "guardrail": "## 🟢 ASTRO GUARDRAILS\n- DO NOT run `biome check --write --unsafe` on `.astro` files (destroys frontmatter).\n- DO NOT import 'sharp' into runtime bundles."
-    },
     {
       "trigger": "\\b(db|database|drizzle|sql\\w*|postgres\\w*|sqlite\\w*|mysql\\w*)\\b",
       "guardrail": "## 🗄️ DATABASE GUARDRAILS\n- Always batch multiple database statements.\n- DO NOT write destructive migrations (`DROP TABLE`) without explicit user consent."

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

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: ['18.x', '20.x', '22.x', '24.x']
+        node-version: ['22.x', '24.x']
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -23,14 +23,25 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
 
-      - name: Syntax Check
-        run: for f in scripts/*.mjs bin/*.js index.mjs; do node --check "$f" || exit 1; done
+      - 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
+        run: npm test --if-present
 
       - name: Run Jules PR Self-Audit Gatekeeper
-        if: matrix.node-version == '20.x' && github.event_name == 'pull_request' && (startsWith(github.actor, 'google-labs-jules') || contains(github.actor, 'jules'))
+        if: matrix.node-version == '22.x' && github.event_name == 'pull_request'
         run: node scripts/jules-self-audit.mjs
         env:
           CI: "true"

package/JULES_RULES_TEMPLATE.md

@@ -50,9 +50,12 @@ Jules automatically infers test and build verification commands via `scripts/com
 
 - **Read Before Write**: Always inspect target files and surrounding symbol signatures (via grep or view tools) before applying changes.
 - **Scope Locks**: Strictly adhere to designated file bounds. Do NOT modify files outside the explicit task scope or alter shared infrastructural components unless assigned.
+- **Falsifiable Criteria**: Never use unfalsifiable goals ("utterly perfect", "complete refactor"). Define tasks with binary scoreable criteria (e.g. passing test counts, 0 lint errors, explicit hard-fails).
+- **Carry Evidence with Claims**: "It works" means pasting terminal verification output. Exit code 0 alone proves only process survival; inspect outputs/artifacts to prove function.
+- **No Test Weakening Rule**: Never make a test pass by deleting assertions, commenting out checks, or weakening requirements. Leave unmet requirements RED with clear fix rationale.
+- **Explicit File Ownership**: Sequence parallel swarm agents with explicit non-overlapping file ownership to prevent concurrent drift.
 - **Rebase Before PR**: Fetch latest `main`, rebase onto `origin/main`, re-execute verification suite. If the resulting diff is empty, close/abort PR without pushing.
 - **Minimal Interference**: Preserve existing function signatures, comments, and style conventions.
-- **Falsifiable Claims**: Base all code changes on explicit error logs, file paths, line numbers, or test results.
 - **No Token Bloat**: Exclude lockfiles, minified bundles, and binary assets from diff representations.
 
 ---
@@ -99,8 +102,10 @@ Follow all rules strictly.
 TASK: <description>
 
 HARD CONSTRAINTS:
-- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, astro.config.mjs, wrangler.jsonc, or .github/ files. Enforced in CI by Agent Scope Guard.
+- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, or .github/ files. Enforced in CI by Agent Scope Guard.
 - Diff Payload Governor: Keep total diff payload under 75 KB (`git diff | wc -c`) to prevent API truncation (~80 KB limit).
+- Falsifiable & Evidence-Based: Attach full terminal verification output to PR. Never weaken assertions or delete failing tests to force a pass.
+- Declare Scope Deviations: If modifying files outside task bounds, explicitly state rationale in PR.
 - Verify before finishing: Run full type-check, lint, and unit test suites.
 - BEFORE opening the PR: Run `git fetch origin main && git rebase origin/main`, then re-verify. If the rebase leaves an empty diff, the work already landed — do NOT submit.
 - Delete ALL temporary files (.py, .sh, .patch, debug logs) before submitting.

package/README.md

@@ -22,29 +22,109 @@ To use this kit, you will need:
 - A Google Jules REST API key (set as `JULES_API_KEY`) **OR** the native `jules` binary in your PATH.
 
 ## Quick Start
-Navigate to your project root and run:
+Initialize your repository:
 ```bash
-npx jules-orchestrator-kit
-npm run jules:create "Refactor Auth"
-npm run jules:queue
+npx jules-orchestrator-kit init
 ```
 
-> 💡 **Vendored Scripts Architecture**:
-> `npx jules-orchestrator-kit` (or `npx jules-init`) copies zero-dependency orchestration scripts directly into your project's `./scripts/` directory. This ensures full code transparency, auditability, and zero external dependency risk in CI.
-> To update vendored scripts to the latest release, run `npx jules-orchestrator-kit --force`.
+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.
 
 ---
 
 ## How It Works
 
-1. **You Assign Task:** Define what needs fixing or building.
+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 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
+    
+    note over Orc,Git: Phase 1: Security Redaction & Provisioning
+    Orc->>Orc: Redact Secrets (Entropy > 3.6) & Enforce Dynamic Guardrails
+    Orc->>+Git: Provision Isolation Sandbox (git worktree)
+    Git-->>-Orc: Sandbox Ready
+    
+    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: Tiered Verification & Gatekeeping
+        Orc->>+Gate: Trigger Self-Audit (trusted origin/main rules)
+        
+        Gate->>+Git: Scope Audit (`git diff -z --name-only` vs forbidden_paths)
+        Git-->>-Gate: Diff Stats & File List
+        
+        alt Scope Breach (Forbidden Path OR Diff Payload > 75 KB)
+            Gate-->>Orc: Security / Scope Violation Detected
+            Orc->>Orc: Record Telemetry (metrics.jsonl)
+            Orc-->>Trigger: Abort Execution (Exit 3)
+            break Fatal Security Error
+                Orc->>Git: Teardown Worktree Sandbox
+            end
+        else Scope Verification Passed
+            Gate->>+Git: Run Dynamic Verification (`testCmd` & `buildCmd`)
+            Git-->>-Gate: stdout / stderr verification results
+        end
+
+        alt 100% Verification Suite Passed
+            Gate-->>-Orc: Verification Success
+            Orc->>+Git: Commit & Push to Remote Branch / PR
+            Git-->>-Orc: PR Ready
+            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
+```
+
 > 💡 **Core Architectural Invariants**:
 > - **Zero-Trust Base-Branch Security**: Security rules (`forbidden_paths`) are fetched exclusively from `origin/main` (never untrusted PR branches).
+> - **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.
 > - **Dynamic Command Resolution (`command-resolver.mjs`)**: Auto-detects workspace boundaries (Turborepo, pnpm, Nx, Cargo, pytest, npm).
 >
 > 🔍 For a deep dive into the execution protocol, see the [Architecture & Pipeline Flow](docs/architecture.md).
@@ -96,13 +176,16 @@ If no API key is configured, the kit seamlessly falls back to invoking your loca
 **3. Programmatic Node.js SDK (`index.mjs`)**
 Downstream Node.js tools, MCP servers, and LLM orchestrators can import kit functions directly:
 ```js
-import { runSelfAudit, scanCodebaseForTodos, resolveProjectCommands } from "jules-orchestrator-kit";
+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");
 
-// Run pre-flight sandbox check
-await runPreflightSandbox();
+// Programmatically dispatch tasks
+await dispatch({ title: "Refactor Auth", prompt: cleanPrompt });
 
-// Scan codebase for TODO/FIXME tasks
-const tasks = scanCodebaseForTodos(process.cwd());
+// Run 4-phase safety gate audit
+const audit = await gate({ base: "main" });
 ```
 
 ---
@@ -149,13 +232,21 @@ All commands are registered in `package.json` and can be run via `npm run <comma
 | `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 the real-time status of all queued and completed tasks |
+| `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 |
@@ -167,6 +258,7 @@ All commands are registered in `package.json` and can be run via `npm run <comma
 | `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`) |
@@ -193,19 +285,19 @@ The Gatekeeper (`jules-self-audit.mjs` and related scripts) uses standard exit c
 | Code | Meaning | Action Taken |
 | ---- | ------- | ------------ |
 | `0`  | **Success** | All tests and security checks passed. |
-| `1`  | **General Error** | Missing dependencies, syntax error, or general failure. |
-| `2`  | **Setup / Context Error** | Git not found, invalid `BASE_BRANCH`, or trusted base branch extraction failure. |
-| `3`  | **Security 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 or is disabled. |
-| `5`  | **Diff Payload Too Large** | Diff payload size exceeded 75 KB payload governor limit. Split task. |
-| `6`  | **Secret Leak Prevented** | Secret-like pattern detected in diff. Aborted immediately. |
+| `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. |
 
 ---
 
 ## Contributing
 We welcome contributions! Please follow these core principles:
-1. **Zero External Dependencies**: Use ONLY native Node.js built-in modules (`node:fs`, `node:path`, `node:child_process`, `node:crypto`, `node:util`).
+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.

package/bin/agentctl.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig, resolveRoot, detectStack } from "../src/config.mjs";
+import { gate, dispatch, run } from "../src/engine.mjs";
+import { acquireLock, releaseLock, lockStatus, checkDailyBudget, getQueueDir, ensureDir } from "../src/state.mjs";
+import { worktreePrune } from "../src/git.mjs";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function printHelp() {
+  console.log(`
+🚀 agentctl v0.9.0 — Universal Agent Orchestrator & Safety Gatekeeper
+
+Usage: agentctl <command> [options]
+
+Commands:
+  dispatch              Dispatch a single task to an AI agent
+  gate | audit          Run CI security and verification gate against current branch
+  queue                 Run pending task queue
+  swarm                 Run parallel task swarm
+  clean                 Clean stale branches, worktrees, locks, and ledgers
+  lock <action>         Manage mutex locks (acquire | release | status | cleanup)
+  doctor                Run system diagnostics and stack resolution checks
+  init                  Scaffold .agent/ directory and config.yml
+  version               Output agentctl version
+
+Options:
+  --dry-run, -d         Simulate action without making API calls or modifying git
+  --json, -j            Emit machine-readable JSON output
+  --help, -h            Show command help
+`);
+}
+
+async function main() {
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log("agentctl v0.9.0");
+    process.exit(0);
+  }
+
+  const root = resolveRoot();
+  const config = loadConfig(root);
+
+  switch (command) {
+    case "dispatch": {
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          title: { type: "string", short: "t" },
+          prompt: { type: "string", short: "p" },
+          "prompt-file": { type: "string", short: "f" },
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      let promptContent = values.prompt || "";
+      if (values["prompt-file"] && existsSync(values["prompt-file"])) {
+        promptContent = readFileSync(values["prompt-file"], "utf-8");
+      }
+
+      if (!promptContent && args[1] && !args[1].startsWith("-")) {
+        promptContent = args.slice(1).join(" ");
+      }
+
+      if (!promptContent) {
+        console.error("Error: --prompt or --prompt-file is required.");
+        process.exit(1);
+      }
+
+      const task = {
+        title: values.title || "CLI Dispatch Task",
+        prompt: promptContent,
+      };
+
+      try {
+        const session = await dispatch(task, { root, config, dryRun: values["dry-run"] });
+        if (values.json) {
+          console.log(JSON.stringify({ ok: true, session }, null, 2));
+        } else {
+          console.log(`\n✅ Task Dispatched Successfully!`);
+          console.log(`   Session ID  : ${session.id}`);
+          console.log(`   Session URL : ${session.url || "N/A"}`);
+        }
+        process.exit(0);
+      } catch (err) {
+        if (values.json) {
+          console.log(JSON.stringify({ ok: false, error: err.message, code: err.code || 1 }, null, 2));
+        } else {
+          console.error(`❌ Dispatch Failed: ${err.message}`);
+        }
+        process.exit(err.code || 1);
+      }
+      break;
+    }
+
+    case "gate":
+    case "audit": {
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          base: { type: "string", short: "b", default: config.baseBranch || "main" },
+          fix: { type: "boolean" },
+          "allow-protected": { type: "boolean" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+
+      const res = await gate({
+        root,
+        config,
+        base: values.base,
+        fix: values.fix,
+        allowProtected: values["allow-protected"],
+      });
+
+      if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        console.log(`\n🛡️ agentctl Safety Gate Audit Results (Base: ${values.base})`);
+        console.log(`-----------------------------------------------------`);
+        for (const p of res.phases) {
+          const status = p.ok ? "✅ PASS" : "❌ FAIL";
+          console.log(`  Phase [${p.phase.toUpperCase()}] : ${status}`);
+          if (p.violations) {
+            p.violations.forEach((v) => console.log(`     - Violation: ${v.file} (Rule: ${v.rule})`));
+          }
+          if (p.findings) {
+            p.findings.forEach((f) => console.log(`     - Finding: ${f.id} at line ${f.line}`));
+          }
+        }
+        console.log(`-----------------------------------------------------`);
+        console.log(`Overall Result: ${res.ok ? "APPROVED (Exit 0)" : `REJECTED (Exit ${res.code})`}\n`);
+      }
+
+      process.exit(res.code);
+      break;
+    }
+
+    case "queue": {
+      const queueDir = getQueueDir(root);
+      const files = readdirSync(queueDir).filter((f) => f.endsWith(".md"));
+      console.log(` Found ${files.length} queued task(s) in .agent/queue/`);
+      if (files.length > 0) {
+        const tasks = files.map((f) => ({
+          id: f,
+          title: f.replace(/\.md$/, ""),
+          prompt: readFileSync(join(queueDir, f), "utf-8"),
+        }));
+        const results = await run(tasks, { root, config });
+        console.log(`\nProcessed ${results.length} tasks.`);
+      }
+      process.exit(0);
+      break;
+    }
+
+    case "swarm": {
+      console.log("🚀 Running Swarm Orchestrator...");
+      const queueDir = getQueueDir(root);
+      const files = readdirSync(queueDir).filter((f) => f.endsWith(".md"));
+      if (files.length === 0) {
+        console.log("No pending tasks found for swarm.");
+        process.exit(0);
+      }
+      const tasks = files.map((f) => ({
+        id: f,
+        title: f.replace(/\.md$/, ""),
+        prompt: readFileSync(join(queueDir, f), "utf-8"),
+      }));
+      const results = await run(tasks, { root, config, concurrency: config.limits.concurrency || 3 });
+      console.log(`Swarm completed ${results.length} tasks.`);
+      process.exit(0);
+      break;
+    }
+
+    case "clean": {
+      console.log("🧹 Running System Cleanup...");
+      worktreePrune(root);
+      console.log("  ✅ Pruned stale Git worktrees.");
+      process.exit(0);
+      break;
+    }
+
+    case "lock": {
+      const action = args[1];
+      if (action === "acquire") {
+        const agent = args[2] || "agent";
+        const taskId = args[3] || "task-1";
+        const filePaths = args.slice(4);
+        const res = acquireLock(agent, taskId, filePaths, root);
+        if (res.ok) {
+          console.log(`✅ Acquired lock for ${taskId}`);
+        } else {
+          console.log(`❌ Lock conflict detected: held by ${res.holder}`);
+          process.exit(1);
+        }
+      } else if (action === "release") {
+        const taskId = args[2] || "task-1";
+        const ok = releaseLock(taskId, root);
+        if (ok) {
+          console.log(`✅ Released lock for ${taskId}`);
+        } else {
+          console.log(`❌ Lock for ${taskId} not found or release failed`);
+          process.exit(1);
+        }
+      } else {
+        const locks = lockStatus(root);
+        console.log(`Active Locks (${locks.length}):`, locks);
+      }
+      process.exit(0);
+      break;
+    }
+
+    case "doctor": {
+      console.log(`\n🔍 agentctl System Diagnostics (v0.9.0)`);
+      console.log(`--------------------------------------------------`);
+      console.log(`  Project Root     : ${root}`);
+      console.log(`  Config File      : ${config._file || "None (Using defaults)"}`);
+      console.log(`  Detected Stack   : ${detectStack(root).stack}`);
+      console.log(`  Test Command     : ${config.verify.test || "(None)"}`);
+      console.log(`  Build Command    : ${config.verify.build || "(None)"}`);
+      const budget = checkDailyBudget(root, config.limits.dailyTasks);
+      console.log(`  Daily Budget     : ${budget.used} / ${budget.budget} sessions used`);
+      console.log(`--------------------------------------------------\n`);
+      process.exit(0);
+      break;
+    }
+
+    case "init": {
+      const agentDir = join(root, ".agent");
+      ensureDir(agentDir);
+      const configPath = join(agentDir, "config.yml");
+      if (!existsSync(configPath)) {
+        writeFileSync(
+          configPath,
+          `version: 1
+provider: jules
+limits:
+  diff_kb: 75
+  daily_tasks: 300
+branch_prefix: agent/
+base_branch: main
+`,
+          "utf-8"
+        );
+        console.log(`✅ Created .agent/config.yml`);
+      } else {
+        console.log(`ℹ️ .agent/config.yml already exists.`);
+      }
+      process.exit(0);
+      break;
+    }
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`[FATAL ERROR] ${err.message}`);
+  process.exit(err.code || 1);
+});

package/bin/init.js

@@ -157,7 +157,7 @@ if (!fs.existsSync(yamlConfigPath) || isForce) {
 version: 2
 test_cmd: "${detected.testCmd || "npm test"}"
 build_cmd: "${detected.buildCmd || "npm run build"}"
-forbidden_paths: [".github/**", "**/secrets/**", "**/*.pem", "**/lock-manager/**"]
+forbidden_paths: [".github/**", "**/.env*", "**/*.pem", "**/lock-manager*"]
 `;
   fs.writeFileSync(yamlConfigPath, yamlContent, "utf-8");
   console.log("✅ Created: .agent/jules.yml");