jules-orchestrator-kit 0.8.5 → 0.9.4

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/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.
 
 ---
@@ -101,6 +104,8 @@ TASK: <description>
 HARD CONSTRAINTS:
 - 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,16 +22,21 @@ 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.
 
 ---
 
@@ -53,6 +58,7 @@ sequenceDiagram
     
     box "Control Plane" #E8F4F8
         participant Orc as Orchestrator Core
+        participant Envelope as Task Envelope Validator
         participant Gate as Self-Audit Gatekeeper
     end
     
@@ -61,12 +67,19 @@ sequenceDiagram
         participant Git as Git Worktree Sandbox
     end
 
-    Trigger->>+Orc: Dispatch Task Payload
+    Trigger->>+Orc: Dispatch Task Payload / Envelope
     
-    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
+    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
@@ -75,28 +88,29 @@ sequenceDiagram
         Git-->>-API: Changes Written
         API-->>-Orc: Execution Complete
         
-        note over Orc,Gate: Phase 3: Tiered Verification & Gatekeeping
+        note over Orc,Gate: Phase 3: Multi-Gate Verification & Risk Classification
         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
+        Gate->>+Git: Run Scope, Payload & Stale-Base Audit (`git diff`)
+        Git-->>-Gate: Diff Stats & Base Commit Age
         
-        alt Scope Breach (Forbidden Path OR Diff Payload > 75 KB)
-            Gate-->>Orc: Security / Scope Violation Detected
+        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 Error
+            break Fatal Security or Base Error
                 Orc->>Git: Teardown Worktree Sandbox
             end
-        else Scope Verification Passed
-            Gate->>+Git: Run Dynamic Verification (`testCmd` & `buildCmd`)
-            Git-->>-Gate: stdout / stderr verification results
+        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 Passed
-            Gate-->>-Orc: Verification Success
+        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
+            Git-->>-Orc: PR Ready (Attached Execution Receipts)
             Orc->>Orc: Record Telemetry (metrics.jsonl)
             Orc-->>Trigger: Dispatch Succeeded (Exit 0)
             break Task Completed
@@ -117,10 +131,12 @@ sequenceDiagram
 ```
 
 > 💡 **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.
-> - **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).
 
@@ -171,16 +187,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, dispatchTask, anonymizePii, verifyLedgerIntegrity, validateJulesConfig } 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");
 
 // Programmatically dispatch tasks
-await dispatchTask({ title: "Refactor Auth", prompt: cleanPrompt });
+await dispatch({ title: "Refactor Auth", prompt: cleanPrompt });
 
-// Verify cryptographic hash chain of event ledgers
-const integrity = verifyLedgerIntegrity(".agent/state/sessions/2026-08-03.jsonl");
+// Run 4-phase safety gate audit
+const audit = await gate({ base: "main" });
 ```
 
 ---
@@ -227,14 +243,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: squash-merges passing, disjoint Jules PRs |
+| `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 |

package/bin/agentctl.mjs

@@ -0,0 +1,281 @@
+#!/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.4 — 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
+  mcp                   Start stdio Model Context Protocol (MCP) server
+  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.4");
+    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;
+    }
+
+    case "mcp": {
+      const { startMcpServer } = await import("../src/mcp.mjs");
+      startMcpServer();
+      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/mcp-server.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { startMcpServer } from "../src/mcp.mjs";
+
+startMcpServer();

package/index.mjs

@@ -1,12 +1,39 @@
 /**
- * jules-orchestrator-kit Node.js SDK
- * Primary entrypoint for programmatically orchestrating Google Jules workflows.
- * Zero runtime dependencies.
+ * Google Jules Orchestrator Kit - Node.js SDK (v0.9.0)
+ *
+ * Exposes core orchestrator functions for programmatically driving agent tasks,
+ * security auditing, repo gating, and state operations.
  */
 
+export { loadConfig, detectStack, resolveVerify, resolveRoot, normalizePath } from "./src/config.mjs";
+export {
+  shannonEntropy,
+  redactSecrets,
+  anonymizePii,
+  matchesGlob,
+  checkScope,
+  scanDiff,
+} from "./src/security.mjs";
+export { git, runCmd, changedFiles, diffBytes, diffText } from "./src/git.mjs";
+export { createProvider, JULES_PRESET, CLAUDE_PRESET, CODEX_PRESET } from "./src/provider.mjs";
+export {
+  appendLedger,
+  readLedger,
+  withBudget,
+  checkDailyBudget,
+  acquireLock,
+  releaseLock,
+  lockStatus,
+} from "./src/state.mjs";
+export { gate, dispatch, repair, run } from "./src/engine.mjs";
+export { validateEnvelope } from "./src/envelope.mjs";
+export { checkAssetIntegrity } from "./src/asset_integrity.mjs";
+export { classifyRiskTier, RISK_TIERS } from "./src/risk.mjs";
+export { checkRulesBudget } from "./src/rules_budget.mjs";
+
+// Legacy SDK shims for backward compatibility
 export { resolveProjectCommands, resolveWorkspaceExecutionBoundary } from "./scripts/command-resolver.mjs";
-export { runSelfAudit, runPreflightSandbox, loadForbiddenPatterns, loadAllowedPatterns, matchGlob, validateJulesConfig } from "./scripts/jules-self-audit.mjs";
+export { runSelfAudit, runPreflightSandbox } from "./scripts/jules-self-audit.mjs";
 export { scanCodebaseForTodos, runScanner } from "./scripts/jules-scan-todos.mjs";
-export { log, logToHistory, ensureDir, resolveMarkdownConflict, redactSecrets, anonymizePii, verifyLedgerIntegrity, loadEnv } from "./scripts/utils.mjs";
 export { getDynamicGuardrails, dispatchTask } from "./scripts/jules-dispatch.mjs";
 export { classifyQueueFailure } from "./scripts/jules-queue-runner.mjs";